` (http/https/mailto), `
` en omhulsels als `` worden herschreven of weggelaten. `javascript:`-, `data:`- en `http:`-afbeeldingen worden niet geladen; links met een ander schema dan http/https/mailto worden `#`. De CSP staat `img-src 'self' https: data:` toe; afbeeldingen krijgen `referrerpolicy="no-referrer"` en `loading="lazy"`. Een README in een submap staat onder de bestandslijst van die map; een `.md`-bestand wordt gerenderd, met de bron in een uitklapblok. Afbeeldingen zijn nooit breder dan de kolom (`max-width: min(100%, 100cqw)`, `height: auto`); in een tabel maximaal 32rem of de kolombreedte, en een brede tabel scrolt binnen haar eigen vak.
- 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. CI kan per project worden gepauzeerd (instellingen of `ci_paused` op `PUT /api/v1/projects/{owner}/{repo}`): er worden dan geen nieuwe pipelines in de wachtrij gezet; jobs die al lopen of wachten, lopen wel af.
- 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).
- 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.
- Periodiek onderhoud van de bare repositories (`git gc --auto`, plus `git maintenance` voor loose objects en incremental-repack als de git-binary dat kent). Standaard elke 24 uur (`git.maintenance_interval`; `off` of `0` zet het uit). Eén repo tegelijk, met lage prioriteit (`nice -n 19`) en gits eigen locking, nooit `--prune=now`. Een fout op één repo slaat die over. Installatiebeheerders zien de status en kunnen een ronde starten via `GET`/`POST /api/v1/admin/git-maintenance`.
- REST-API. Het schema staat op `/api/v1/openapi.json`.
- Self-update: de instantie installeert een nieuw AUR-pakket met pacman.
- Een of meer losse backup servers (`bluegit-backup`, ook in deze repository, zie [docs/BACKUP-SERVER.md](docs/BACKUP-SERVER.md)) onder Beheer > Backup: per server een Backupserver-Key, een melding na elke wijziging, de archieflijst, een rollback met waarschuwing en de bediening en instellingen van de backup server zelf. Past een backup server niet bij deze BlueGit (een van de twee is verouderd), dan zien beheerders bovenaan elke pagina een waarschuwing. Zie [docs/BACKUP.md](docs/BACKUP.md).
- 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.
Op andere distro's gebruik je de pakketten van de [releasepagina](https://git.timfalken.com/timfa/bluegit/-/releases). Elke release (tag `v*`) heeft voor `bluegit`, `bluegit-runner` en `bluegit-backup`:
- losse binaries voor linux amd64 en arm64 (`bluegit-linux-amd64`, …);
- `.deb` voor Ubuntu Server en Debian (`apt install ./bluegit_amd64.deb`);
- `.rpm` voor RHEL, Rocky, Alma en Fedora (`dnf install ./bluegit.x86_64.rpm`);
- `.pkg.tar.zst` voor Arch (`pacman -U bluegit-x86_64.pkg.tar.zst`);
- `SHA256SUMS` over alle bestanden.
De pakketten installeren de systemd-unit, de gebruiker (`bluegit`, `bluegit-runner`, `bluegit-backup`) en de config onder `/etc//`, net als de AUR-pakketten. Ze zetten de service niet aan. De self-update (bluegit-update) zit alleen in het AUR-pakket. ` --version` toont de tag. De CI test elk pakket in ubuntu:24.04, debian:12, rockylinux:9, fedora en archlinux voordat er een release komt.
Hoe het AUR-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).
## Microsoft Entra ID
Details en de OIDC-controles staan in [docs/AUTH.md](docs/AUTH.md). Kort, stap voor stap:
1. Open het [Microsoft Entra-beheercentrum](https://entra.microsoft.com) → 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`, `email` en `User.Read`. De eerste drie horen bij OpenID Connect. `User.Read` is nodig om bij het aanmelden de profielfoto op te halen bij Microsoft Graph (`GET https://graph.microsoft.com/v1.0/me/photo/$value`). Voeg *Microsoft Graph → User.Read* (gedelegeerd) toe onder API-machtigingen van de app-registratie en geef desnoods admin-toestemming. Zonder foto (404) toont BlueGit initialen; een handmatig geüploade avatar wordt niet overschreven.
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):
```yaml
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.
```yaml
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
```
```shell
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:
```shell
git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git
```
## Documentatie
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) beschrijft het proces, de schijf en waarom het één binary is.
- [docs/AUTH.md](docs/AUTH.md) beschrijft de OAuth-koppeling en Microsoft Entra ID.
- [docs/INGRESS.md](docs/INGRESS.md) beschrijft TLS, de publieke SSH-poort, en hoe Apache encoded slashes (`%2F`) doorlaat.
- [docs/CI.md](docs/CI.md) beschrijft `blue-ci-cd.yml` en Steve.
- [docs/AUR.md](docs/AUR.md) beschrijft het pakket en de self-update.
- [docs/BEHEER.md](docs/BEHEER.md) beschrijft de installatie op git.timfalken.com.
- [docs/BACKUP.md](docs/BACKUP.md) beschrijft de koppeling met losse backup servers (bluegit-backup): Backupserver-Keys, meldingen, archieven, rollback en bediening vanuit BlueGit.
- [docs/BACKUP-SERVER.md](docs/BACKUP-SERVER.md) beschrijft de backup server zelf, [docs/BACKUP-PROTOCOL.md](docs/BACKUP-PROTOCOL.md) het protocol.
- [docs/ASSUMPTIONS.md](docs/ASSUMPTIONS.md) bevat de aannames.
- [docs/MIGRATIE.md](docs/MIGRATIE.md) beschrijft de overstap van de user-unit naar de system-service.
- [docs/ROADMAP.md](docs/ROADMAP.md) en [docs/VRAGEN.md](docs/VRAGEN.md) houden bij wat nog openstaat en welke besluiten al vastliggen.
## Tests
```shell
go test ./...
```
## Licentie
MIT. Zie [LICENSE](LICENSE).