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.
Wat het doet
- Repositories van een gebruiker of een groep, met bestanden, commits, branches, tags en releases.
- Op de project-overzichtspagina staat een commitgrafiek in de lege ruimte naast de centrale kolom, als er plek is. 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.mdvult 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/baseen 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.
| Rol | Lezen | Schrijven op een gewone branch | Beschermde branch | Geheimen, webhooks, leden, verwijderen |
|---|---|---|---|---|
| Alleen lezen | ja | nee | nee | nee |
| Ontwikkelaar | ja | ja | nee | nee |
| Beheerder | ja | ja | ja | ja |
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_fileofBLUEGIT_AUTH_CLIENT_SECRETbij, en herstart. - Verkeerde tenant:
auth.tenant_idhoort bij een andere directory, oftidin 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
- docs/ARCHITECTURE.md beschrijft het proces, de schijf en waarom het één binary is.
- docs/AUTH.md beschrijft de OAuth-koppeling en Microsoft Entra ID.
- docs/INGRESS.md beschrijft TLS en de publieke SSH-poort.
- docs/CI.md beschrijft
blue-ci-cd.ymlen Steve. - docs/AUR.md beschrijft het pakket en de self-update.
- docs/BEHEER.md beschrijft de installatie op git.timfalken.com.
- docs/MIGRATIE.md beschrijft de overstap van de user-unit naar de system-service.
- docs/ROADMAP.md en docs/VRAGEN.md houden bij wat nog openstaat en welke besluiten al vastliggen.
Tests
go test ./...
Licentie
MIT. Zie LICENSE.
Source
| 1 | # BlueGit |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | Er 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 | |
| 7 | Het logo is de blauwe ster: [`assets/logo.svg`](assets/logo.svg). |
| 8 | |
| 9 |  |
| 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 in de lege ruimte naast de centrale kolom, als er plek is. 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 | |
| 27 | Een 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 | |
| 35 | 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. |
| 36 | |
| 37 | ## Installeren |
| 38 | |
| 39 | Op 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 | |
| 43 | Hoe 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 | |
| 47 | Details en de OIDC-controles staan in [docs/AUTH.md](docs/AUTH.md). Kort, stap voor stap: |
| 48 | |
| 49 | 1. Open het [Microsoft Entra-beheercentrum](https://entra.microsoft.com) → Identiteit → Toepassingen → App-registraties → Nieuwe registratie. |
| 50 | 2. Kies één tenant (*Accounts in this organizational directory only* / single tenant). |
| 51 | 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. |
| 52 | 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. |
| 53 | 5. BlueGit vraagt de scopes `openid`, `profile` en `email`. Die horen bij OpenID Connect; er zijn geen extra Graph-rechten nodig voor aanmelden. |
| 54 | 6. Op het overzicht van de app-registratie staan de **Directory (tenant) ID** (`auth.tenant_id`) en de **Application (client) ID** (`auth.client_id`). |
| 55 | |
| 56 | Zet in `/etc/bluegit/config.yml` (geen echte geheimen in dit bestand of in deze docs): |
| 57 | |
| 58 | ```yaml |
| 59 | auth: |
| 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 | |
| 69 | 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. |
| 70 | |
| 71 | 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. |
| 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 |
| 86 | base_url: http://127.0.0.1:8080 |
| 87 | listen: 127.0.0.1:8080 |
| 88 | auth: |
| 89 | mode: dev |
| 90 | dev_user: tim |
| 91 | ssh: |
| 92 | enabled: false |
| 93 | ci: |
| 94 | enabled: false |
| 95 | ``` |
| 96 | |
| 97 | ```shell |
| 98 | go build -o bluegit ./cmd/bluegit |
| 99 | ./bluegit serve --config bluegit.yml |
| 100 | ``` |
| 101 | |
| 102 | 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. |
| 103 | |
| 104 | Een toegangstoken maak je onder Account. Git gebruikt dat token als wachtwoord: |
| 105 | |
| 106 | ```shell |
| 107 | git 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 |
| 124 | go test ./... |
| 125 | ``` |
| 126 | |
| 127 | ## Licentie |
| 128 | |
| 129 | MIT. Zie [LICENSE](LICENSE). |