# 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](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).

Het logo is de blauwe ster: [`assets/logo.svg`](assets/logo.svg).

![BlueGit](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.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](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.
- 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](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` 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):

```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 en de publieke SSH-poort.
- [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/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).
