BlueGit

timfa bluegit

Files

bluegit / README.md

README.md

README.md 8.7 KiB Download Raw

BlueGit

BlueGit is een self-hosted git-platform. Het is één Go-binary: de website, smart HTTP, de REST-API en de SSH-listener draaien in hetzelfde proces. Metadata staat in SQLite. Git-objecten staan in bare repositories op een schijf die de beheerder kiest. Docker wordt alleen gebruikt om CI-jobs te draaien.

Er is geen lokaal wachtwoord. Aanmelden gaat via de OAuth-flow van auth.timfalken.com (auth.mode: oauth, de standaard) of via Microsoft Entra ID (auth.mode: entra, één tenant). Zie docs/AUTH.md.

Het logo is de blauwe ster: assets/logo.svg.

BlueGit

Wat het doet

  • Repositories van een gebruiker of een groep, met bestanden, commits, branches, tags en releases.
  • Op de project-overzichtspagina staat een commitgrafiek links van de centrale kolom, als er plek is. Elke commit staat op één regel; de lijnen lopen in verticale lanes met afgeronde 90-graden bochten, en de avatar is de commitknoop. De tekst begint in één kolom, rechts van de meest rechtse lane. Elke avatar staat exact op de lane van die commit. De grafiek wordt niet verkleind; te lange committekst krijgt een ellipsis. Past de grafiek links niet zonder de centrale kolom onbruikbaar te maken (bijvoorbeeld 1280px met sidebar), dan hangt hij rechts, anders blijft hij verborgen. De lijn van de in de dropdown gekozen branch gloeit. De hoofdbranch gebruikt de BlueGit-blauw; andere branches krijgen een vaste kleur uit hun naam. De grafiek wordt in het geheugen bewaard (LRU) en bij een push ververst, zodat herhaald laden geen git-I/O op schijf doet.
  • Merge requests met reviews, squash en het verwijderen van de bronbranch na een merge.
  • Issues, met beschrijvingssjablonen in .bluegit/issue_templates. Merge requests gebruiken .bluegit/merge_request_templates. Default.md vult een lege beschrijving. Dezelfde namen onder .gitlab/ zijn een terugval.
  • Een ingebouwde CI-runner, Steve. Het bestand is blue-ci-cd.yml. Elke job draait in een eigen container. image: bluegit/base en de andere aliassen zijn image-presets die Steve lokaal bouwt.
  • Jobs die je niet halverwege wilt stoppen (FTP-upload, databasemigratie) markeer je met doNotInterrupt: true: BlueGit stopt ze nooit automatisch, een nieuwere pipeline op dezelfde ref wacht erop, en handmatig stoppen vraagt om bevestiging. Zie docs/CI.md.
  • Webhooks op een repository of een groep, met presets, een eigen body en een overzicht van de laatste afleveringen.
  • Geheimen als omgevingsvariabelen in een job. Een beschermd geheim gaat alleen mee op een beschermde branch of een tag die op een beschermd tagpatroon past.
  • Groepen, met eigen leden, geheimen en webhooks.
  • Git over SSH en over HTTPS.
  • REST-API. Het schema staat op /api/v1/openapi.json.
  • Self-update: de instantie installeert een nieuw AUR-pakket met pacman.
  • Linkpreviews: een gedeelde pagina krijgt een kaart via Open Graph, oEmbed en /-/card.png.

Een repository hoort bij een gebruiker of bij een groep. De hoogste rol telt.

RolLezenSchrijven op een gewone branchBeschermde branchGeheimen, webhooks, leden, verwijderen
Alleen lezenjaneeneenee
Ontwikkelaarjajaneenee
Beheerderjajajaja

De installatiebeheerder is geen beheerder van andermans repository. Een onbeschermd geheim kan een pipeline uitlezen via blue-ci-cd.yml. Markeer het als beschermd als het alleen op een beschermde branch mee mag.

Installeren

Op Arch installeer je het AUR-pakket bluegit. De configuratie staat in /etc/bluegit/config.yml. De systemd-service heet bluegit.service.

bluegit example-config print een voorbeeld. Het clientgeheim hoort in /etc/bluegit/client_secret (mode 0600) of als BLUEGIT_AUTH_CLIENT_SECRET in /etc/bluegit/secret.env. Zonder configuratie én geheim start de service niet. De eerste aangemelde gebruiker wordt installatiebeheerder en kiest in /setup de schijf voor de repositories.

Hoe het pakket gepubliceerd wordt en hoe de self-update via pacman werkt, staat in docs/AUR.md. De stappen voor de installatie op git.timfalken.com staan in docs/BEHEER.md.

Microsoft Entra ID

Details en de OIDC-controles staan in docs/AUTH.md. Kort, stap voor stap:

1. Open het Microsoft Entra-beheercentrum → Identiteit → Toepassingen → App-registraties → Nieuwe registratie. 2. Kies één tenant (Accounts in this organizational directory only / single tenant). 3. Platform: Web. De redirect-URI moet exact {base_url}{auth.redirect_path} zijn, het pad dat BlueGit verwacht. auth.redirect_path is standaard /auth/callback, dus bijvoorbeeld https://git.timfalken.com/auth/callback. Een ander pad, schema (http vs https) of een slash te veel of te weinig geeft een redirect-mismatch. 4. Maak onder Certificates & secrets een client secret aan. Noteer de waarde (die is maar één keer zichtbaar) en de verloopdatum; na verlopen stopt aanmelden. 5. BlueGit vraagt de scopes openid, profile en email. Die horen bij OpenID Connect; er zijn geen extra Graph-rechten nodig voor aanmelden. 6. Op het overzicht van de app-registratie staan de Directory (tenant) ID (auth.tenant_id) en de Application (client) ID (auth.client_id).

Zet in /etc/bluegit/config.yml (geen echte geheimen in dit bestand of in deze docs):

auth:
  mode: entra
  tenant_id:     # Directory (tenant) ID
  client_id:     # Application (client) ID
  client_secret_file: /etc/bluegit/client_secret
  redirect_path: /auth/callback
  # issuer alleen voor een andere cloud of een test; leeg =
  # https://login.microsoftonline.com/{tenant_id}/v2.0

Het clientgeheim zet je niet in de yaml als het vermijdbaar is. Alternatieven met exacte namen uit de code: auth.client_secret, auth.client_secret_file (bijvoorbeeld /etc/bluegit/client_secret, mode 0600) of de omgevingsvariabele BLUEGIT_AUTH_CLIENT_SECRET (bijvoorbeeld in /etc/bluegit/secret.env). auth.base_url hoort bij mode: oauth, niet bij entra.

Herstart daarna de service (systemctl restart bluegit). De bestaande knop Aanmelden (in de navigatie, naar /login) start de Entra-flow; er is geen aparte knop. Zonder auth.mode: entra blijft die knop naar auth.timfalken.com gaan.

Accountkoppeling. De BlueGit-gebruiker hangt aan tid + oid uit het ID-token (stabiele auth_id). Dezelfde Entra-gebruiker komt terug op het bestaande account. Een nieuwe login waarvan de afgeleide gebruikersnaam al door een ander account bezet is, wordt geweigerd; er is geen overname via e-mail.

Veelvoorkomende fouten

  • De redirect-URI komt niet exact overeen (pad, schema, host, slash) → redirect mismatch (vaak AADSTS50011).
  • Verlopen client secret → de token-exchange faalt; maak een nieuw geheim, werk auth.client_secret_file of BLUEGIT_AUTH_CLIENT_SECRET bij, en herstart.
  • Verkeerde tenant: auth.tenant_id hoort bij een andere directory, of tid in het token komt niet overeen → aanmelden wordt geweigerd.

Lokaal

auth.mode: dev maakt een sessie zonder de auth-server. De configuratie weigert die modus zodra base_url op git.timfalken.com wijst.

base_url: http://127.0.0.1:8080
listen: 127.0.0.1:8080
auth:
  mode: dev
  dev_user: tim
ssh:
  enabled: false
ci:
  enabled: false
go build -o bluegit ./cmd/bluegit
./bluegit serve --config bluegit.yml

Laat storage_path weg. Na het aanmelden vraagt BlueGit om een absoluut pad dat al bestaat, beschrijfbaar is en minstens 1 GiB vrij heeft. mkdir -p "$PWD/data" en plak dat pad in het scherm. Zet je toch storage_path in het bestand, dan moet dat pad absoluut zijn. Het slaat het scherm over zolang de state-map nog geen keuze bewaart.

Een toegangstoken maak je onder Account. Git gebruikt dat token als wachtwoord:

git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git

Documentatie

Tests

go test ./...

Licentie

MIT. Zie LICENSE.

Source
1# BlueGit
2
3BlueGit is een self-hosted git-platform. Het is één Go-binary: de website, smart HTTP, de REST-API en de SSH-listener draaien in hetzelfde proces. Metadata staat in SQLite. Git-objecten staan in bare repositories op een schijf die de beheerder kiest. Docker wordt alleen gebruikt om CI-jobs te draaien.
4
5Er is geen lokaal wachtwoord. Aanmelden gaat via de OAuth-flow van [auth.timfalken.com](https://auth.timfalken.com) (`auth.mode: oauth`, de standaard) of via Microsoft Entra ID (`auth.mode: entra`, één tenant). Zie [docs/AUTH.md](docs/AUTH.md).
6
7Het logo is de blauwe ster: [`assets/logo.svg`](assets/logo.svg).
8
9![BlueGit](assets/logo.svg)
10
11## Wat het doet
12
13- Repositories van een gebruiker of een groep, met bestanden, commits, branches, tags en releases.
14- Op de project-overzichtspagina staat een commitgrafiek links van de centrale kolom, als er plek is. Elke commit staat op één regel; de lijnen lopen in verticale lanes met afgeronde 90-graden bochten, en de avatar is de commitknoop. De tekst begint in één kolom, rechts van de meest rechtse lane. Elke avatar staat exact op de lane van die commit. De grafiek wordt niet verkleind; te lange committekst krijgt een ellipsis. Past de grafiek links niet zonder de centrale kolom onbruikbaar te maken (bijvoorbeeld 1280px met sidebar), dan hangt hij rechts, anders blijft hij verborgen. De lijn van de in de dropdown gekozen branch gloeit. De hoofdbranch gebruikt de BlueGit-blauw; andere branches krijgen een vaste kleur uit hun naam. De grafiek wordt in het geheugen bewaard (LRU) en bij een push ververst, zodat herhaald laden geen git-I/O op schijf doet.
15- Merge requests met reviews, squash en het verwijderen van de bronbranch na een merge.
16- Issues, met beschrijvingssjablonen in `.bluegit/issue_templates`. Merge requests gebruiken `.bluegit/merge_request_templates`. `Default.md` vult een lege beschrijving. Dezelfde namen onder `.gitlab/` zijn een terugval.
17- Een ingebouwde CI-runner, Steve. Het bestand is `blue-ci-cd.yml`. Elke job draait in een eigen container. `image: bluegit/base` en de andere aliassen zijn image-presets die Steve lokaal bouwt.
18- Jobs die je niet halverwege wilt stoppen (FTP-upload, databasemigratie) markeer je met `doNotInterrupt: true`: BlueGit stopt ze nooit automatisch, een nieuwere pipeline op dezelfde ref wacht erop, en handmatig stoppen vraagt om bevestiging. Zie [docs/CI.md](docs/CI.md#donotinterrupt).
19- Webhooks op een repository of een groep, met presets, een eigen body en een overzicht van de laatste afleveringen.
20- Geheimen als omgevingsvariabelen in een job. Een beschermd geheim gaat alleen mee op een beschermde branch of een tag die op een beschermd tagpatroon past.
21- Groepen, met eigen leden, geheimen en webhooks.
22- Git over SSH en over HTTPS.
23- REST-API. Het schema staat op `/api/v1/openapi.json`.
24- Self-update: de instantie installeert een nieuw AUR-pakket met pacman.
25- Linkpreviews: een gedeelde pagina krijgt een kaart via Open Graph, oEmbed en `/-/card.png`.
26
27Een repository hoort bij een gebruiker of bij een groep. De hoogste rol telt.
28
29| Rol | Lezen | Schrijven op een gewone branch | Beschermde branch | Geheimen, webhooks, leden, verwijderen |
30| --- | --- | --- | --- | --- |
31| Alleen lezen | ja | nee | nee | nee |
32| Ontwikkelaar | ja | ja | nee | nee |
33| Beheerder | ja | ja | ja | ja |
34
35De installatiebeheerder is geen beheerder van andermans repository. Een onbeschermd geheim kan een pipeline uitlezen via `blue-ci-cd.yml`. Markeer het als beschermd als het alleen op een beschermde branch mee mag.
36
37## Installeren
38
39Op Arch installeer je het AUR-pakket `bluegit`. De configuratie staat in `/etc/bluegit/config.yml`. De systemd-service heet `bluegit.service`.
40
41`bluegit example-config` print een voorbeeld. Het clientgeheim hoort in `/etc/bluegit/client_secret` (mode `0600`) of als `BLUEGIT_AUTH_CLIENT_SECRET` in `/etc/bluegit/secret.env`. Zonder configuratie én geheim start de service niet. De eerste aangemelde gebruiker wordt installatiebeheerder en kiest in `/setup` de schijf voor de repositories.
42
43Hoe het pakket gepubliceerd wordt en hoe de self-update via pacman werkt, staat in [docs/AUR.md](docs/AUR.md). De stappen voor de installatie op git.timfalken.com staan in [docs/BEHEER.md](docs/BEHEER.md).
44
45## Microsoft Entra ID
46
47Details en de OIDC-controles staan in [docs/AUTH.md](docs/AUTH.md). Kort, stap voor stap:
48
491. Open het [Microsoft Entra-beheercentrum](https://entra.microsoft.com) → Identiteit → Toepassingen → App-registraties → Nieuwe registratie.
502. Kies één tenant (*Accounts in this organizational directory only* / single tenant).
513. Platform: **Web**. De redirect-URI moet exact `{base_url}{auth.redirect_path}` zijn, het pad dat BlueGit verwacht. `auth.redirect_path` is standaard `/auth/callback`, dus bijvoorbeeld `https://git.timfalken.com/auth/callback`. Een ander pad, schema (`http` vs `https`) of een slash te veel of te weinig geeft een redirect-mismatch.
524. Maak onder *Certificates & secrets* een client secret aan. Noteer de waarde (die is maar één keer zichtbaar) en de verloopdatum; na verlopen stopt aanmelden.
535. BlueGit vraagt de scopes `openid`, `profile` en `email`. Die horen bij OpenID Connect; er zijn geen extra Graph-rechten nodig voor aanmelden.
546. Op het overzicht van de app-registratie staan de **Directory (tenant) ID** (`auth.tenant_id`) en de **Application (client) ID** (`auth.client_id`).
55
56Zet in `/etc/bluegit/config.yml` (geen echte geheimen in dit bestand of in deze docs):
57
58```yaml
59auth:
60 mode: entra
61 tenant_id: # Directory (tenant) ID
62 client_id: # Application (client) ID
63 client_secret_file: /etc/bluegit/client_secret
64 redirect_path: /auth/callback
65 # issuer alleen voor een andere cloud of een test; leeg =
66 # https://login.microsoftonline.com/{tenant_id}/v2.0
67```
68
69Het clientgeheim zet je niet in de yaml als het vermijdbaar is. Alternatieven met exacte namen uit de code: `auth.client_secret`, `auth.client_secret_file` (bijvoorbeeld `/etc/bluegit/client_secret`, mode `0600`) of de omgevingsvariabele `BLUEGIT_AUTH_CLIENT_SECRET` (bijvoorbeeld in `/etc/bluegit/secret.env`). `auth.base_url` hoort bij `mode: oauth`, niet bij entra.
70
71Herstart daarna de service (`systemctl restart bluegit`). De bestaande knop **Aanmelden** (in de navigatie, naar `/login`) start de Entra-flow; er is geen aparte knop. Zonder `auth.mode: entra` blijft die knop naar auth.timfalken.com gaan.
72
73**Accountkoppeling.** De BlueGit-gebruiker hangt aan `tid` + `oid` uit het ID-token (stabiele `auth_id`). Dezelfde Entra-gebruiker komt terug op het bestaande account. Een nieuwe login waarvan de afgeleide gebruikersnaam al door een ander account bezet is, wordt geweigerd; er is geen overname via e-mail.
74
75**Veelvoorkomende fouten**
76
77- De redirect-URI komt niet exact overeen (pad, schema, host, slash) → redirect mismatch (vaak AADSTS50011).
78- Verlopen client secret → de token-exchange faalt; maak een nieuw geheim, werk `auth.client_secret_file` of `BLUEGIT_AUTH_CLIENT_SECRET` bij, en herstart.
79- Verkeerde tenant: `auth.tenant_id` hoort bij een andere directory, of `tid` in het token komt niet overeen → aanmelden wordt geweigerd.
80
81## Lokaal
82
83`auth.mode: dev` maakt een sessie zonder de auth-server. De configuratie weigert die modus zodra `base_url` op `git.timfalken.com` wijst.
84
85```yaml
86base_url: http://127.0.0.1:8080
87listen: 127.0.0.1:8080
88auth:
89 mode: dev
90 dev_user: tim
91ssh:
92 enabled: false
93ci:
94 enabled: false
95```
96
97```shell
98go build -o bluegit ./cmd/bluegit
99./bluegit serve --config bluegit.yml
100```
101
102Laat `storage_path` weg. Na het aanmelden vraagt BlueGit om een absoluut pad dat al bestaat, beschrijfbaar is en minstens 1 GiB vrij heeft. `mkdir -p "$PWD/data"` en plak dat pad in het scherm. Zet je toch `storage_path` in het bestand, dan moet dat pad absoluut zijn. Het slaat het scherm over zolang de state-map nog geen keuze bewaart.
103
104Een toegangstoken maak je onder Account. Git gebruikt dat token als wachtwoord:
105
106```shell
107git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git
108```
109
110## Documentatie
111
112- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) beschrijft het proces, de schijf en waarom het één binary is.
113- [docs/AUTH.md](docs/AUTH.md) beschrijft de OAuth-koppeling en Microsoft Entra ID.
114- [docs/INGRESS.md](docs/INGRESS.md) beschrijft TLS en de publieke SSH-poort.
115- [docs/CI.md](docs/CI.md) beschrijft `blue-ci-cd.yml` en Steve.
116- [docs/AUR.md](docs/AUR.md) beschrijft het pakket en de self-update.
117- [docs/BEHEER.md](docs/BEHEER.md) beschrijft de installatie op git.timfalken.com.
118- [docs/MIGRATIE.md](docs/MIGRATIE.md) beschrijft de overstap van de user-unit naar de system-service.
119- [docs/ROADMAP.md](docs/ROADMAP.md) en [docs/VRAGEN.md](docs/VRAGEN.md) houden bij wat nog openstaat en welke besluiten al vastliggen.
120
121## Tests
122
123```shell
124go test ./...
125```
126
127## Licentie
128
129MIT. Zie [LICENSE](LICENSE).