BlueGit

timfa bluegit

Files

bluegit / docs / ARCHITECTURE.md

ARCHITECTURE.md

feat: eerste basis van BlueGit
timfa project_87923614_bot_3aff574f6f98414b945a8799374f9092 · pushed by timfa · 3 weeks ago
151aa352 History
ARCHITECTURE.md 5.7 KiB Download Raw

Architectuur

BlueGit is één proces. Het bedient de website, de git-HTTP-server, de API en (als het aanstaat) de SSH-listener. Een tweede goroutine plant CI-jobs. Metadata staat in SQLite. Git-objecten staan in bare repositories op de datadisk.

browser ──HTTPS──▶ Caddy ──▶ bluegit (web + smart HTTP + API)
git     ──HTTPS──▶ Caddy ──▶ bluegit ──▶ git http-backend ──▶ pre-receive hook
git     ──SSH:2222─────────▶ bluegit ──▶ git-receive-pack ──▶ dezelfde hook
bluegit ──bearer──▶ auth.timfalken.com
bluegit ──docker run──▶ jobcontainer
jobcontainer ──CI_JOB_TOKEN──▶ API van bluegit (release)
jobcontainer ──SSH-geheim──▶ de host (deploy, gewone SSH)

Waarom deze vorm

De mini-PC moet één ding draaien dat je kunt vervangen door een nieuwe binary. Go levert die binary zonder runtime ernaast. SQLite hoeft geen tweede dienst. De git-binary is toch al nodig voor hooks en merges; smart HTTP gaat daarom via git http-backend in plaats van een eigen implementatie van het pack-protocol.

Docker is alleen de jobgrens die de eis stelt. BlueGit mount de Docker-socket niet in de job. Een job die de host wil wijzigen, doet dat via SSH met een geheim, net als elke andere repository.

Schijf

storage_path is de wortel, in de voorbeeldconfig /mnt/storage/bluegit.

bluegit.db          metadata, mode via het proces van gebruiker bluegit
secret.key          32 bytes, AES-GCM voor geheimen, mode 0600
repos/eigenaar/naam.git
artifacts/job-id/…
releases/eigenaar/naam/tag/…
work/pipeline/job/  tijdelijke clone voor een job
ssh/host_ed25519    hostkey van de git-SSH

Geheimen in de database zijn versleuteld. Sessietokens van de auth-server staan als tekst in SQLite; de bestandsmachtiging van de database is de grens. Versleutelen van die sessies staat op de roadmap.

Auth

De interface auth.Provider heeft AuthorizeURL, Exchange, Extend en Logout. TimFalken praat met auth.timfalken.com. Dev vult dezelfde interface lokaal, zonder wachtwoord, en mag niet aan op het productiedomein.

Na de code-wissel bewaart BlueGit het bearer-token in de sessie. Korter dan zes uur voor het einde wordt POST /api/session/extend aangeroepen. Afmelden trekt het token in met POST /api/logout.

Git en de API gebruiken een apart toegangstoken (bg_…) of, alleen tijdens een job, een job-token (bgj_…). Dat zijn geen wachtwoorden: ze worden één keer getoond, als hash bewaard, en zijn in te trekken. Het OAuth-token leeft 24 uur en is een slechte git-credential.

Details en de eisen van de auth-server staan in AUTH.md.

Rechten

internal/access is bewust los van HTTP en SQL. Resolve kiest de hoogste rol uit: installatiebeheerder, persoonlijke eigenaar, groepslid, rechtstreeks lid. AuthorizeUpdate keurt een pre-receive-regel goed. De hook is die functie, aangeroepen als bluegit hook pre-receive, met de rol en de patronen in de omgeving. Zonder die omgeving weigert de hook, zodat een push om de server heen niet slaagt.

De installatiebeheerder is overal beheerder. Dat is handig op een machine van één persoon, en ruim als er later meer mensen op zitten. Zie de open vragen.

Web

De pagina's zijn serverside HTML uit de binary. De router is de standaard ServeMux van Go 1.22. Een repository staat op /{eigenaar}/{naam}. Git staat op /{eigenaar}/{naam}.git. Vaste paden (/login, /groups, /settings, /api) winnen van die wildcard.

Formulieren sturen een CSRF-token uit de sessie mee. De API gebruikt een bearer-token en geen CSRF.

Push naar pipeline

Na een geslaagde smart-HTTP-push of SSH-push vergelijkt BlueGit de refs. Voor elke bijgewerkte branch leest het blue-ci-cd.yml op die commit. Ontbreekt het bestand, dan gebeurt er niets. Is het ongeldig, dan komt er een mislukte pipeline met de fout in het log, zodat de push zelf niet blokkeert. Jobs waarvan de rules niet kloppen, worden niet aangemaakt.

De runner zet een job op running, kloont de commit naar een werkmap, haalt artifacts van eerdere jobs binnen, en start:

docker run --rm --network <ci.network> -e NAAM …
  -v werkmap:/workspace --entrypoint sh IMAGE /workspace/.bluegit-job.sh

-e NAAM zonder waarde laat Docker de variabele uit de omgeving van BlueGit overnemen. Daardoor blijft een meerregelige SSH-sleutel heel, en staat de waarde niet in de proceslijst. Het netwerk van de container is het gewone Docker-netwerk, niet het hostnetwerk.

CI_JOB_TOKEN hoort bij die ene lopende job. De release-API eist dat het token bij deze repository hoort en dat de job nog loopt. Assets moeten al als artifact van een geslaagde job in dezelfde pipeline bestaan.

Webhooks

Een gebeurtenis gaat naar de webhooks van de repository en, als de repository van een groep is, ook naar die van de groep. Een repository-webhook ziet repositorygeheimen. Een groep-webhook ziet alleen groepgeheimen. Een beschermd geheim gaat mee als de branch van de gebeurtenis beschermd is.

Het branchfilter geldt alleen voor push. Andere gebeurtenissen negeren het. Een onbekend geheim of veld in het sjabloon is een fout en er gaat niets uit, zodat er geen webhook vertrekt met een leeg token.

Vertrouwensgrens

De systeemgebruiker bluegit kan alles lezen wat op de schijf staat, inclusief geheimen (hij heeft secret.key). Mensen op de website kunnen dat niet, behalve een beheerder via het JSON-export dat de auth-server verplicht stelt. CI-jobs zien de geheimen die de regel van beschermde branches toelaat. Ze zien de Docker-socket niet.

Webhooks mogen naar elk http(s)-adres, ook naar iets op het lokale netwerk. Dat is nodig voor een bot naast de mini-PC. Het is ook een manier om een intern adres te raken. Een allowlist staat op de roadmap.

Source
1# Architectuur
2
3BlueGit is één proces. Het bedient de website, de git-HTTP-server, de API en (als het aanstaat) de SSH-listener. Een tweede goroutine plant CI-jobs. Metadata staat in SQLite. Git-objecten staan in bare repositories op de datadisk.
4
5```text
6browser ──HTTPS──▶ Caddy ──▶ bluegit (web + smart HTTP + API)
7git ──HTTPS──▶ Caddy ──▶ bluegit ──▶ git http-backend ──▶ pre-receive hook
8git ──SSH:2222─────────▶ bluegit ──▶ git-receive-pack ──▶ dezelfde hook
9bluegit ──bearer──▶ auth.timfalken.com
10bluegit ──docker run──▶ jobcontainer
11jobcontainer ──CI_JOB_TOKEN──▶ API van bluegit (release)
12jobcontainer ──SSH-geheim──▶ de host (deploy, gewone SSH)
13```
14
15## Waarom deze vorm
16
17De mini-PC moet één ding draaien dat je kunt vervangen door een nieuwe binary. Go levert die binary zonder runtime ernaast. SQLite hoeft geen tweede dienst. De git-binary is toch al nodig voor hooks en merges; smart HTTP gaat daarom via `git http-backend` in plaats van een eigen implementatie van het pack-protocol.
18
19Docker is alleen de jobgrens die de eis stelt. BlueGit mount de Docker-socket niet in de job. Een job die de host wil wijzigen, doet dat via SSH met een geheim, net als elke andere repository.
20
21## Schijf
22
23`storage_path` is de wortel, in de voorbeeldconfig `/mnt/storage/bluegit`.
24
25```text
26bluegit.db metadata, mode via het proces van gebruiker bluegit
27secret.key 32 bytes, AES-GCM voor geheimen, mode 0600
28repos/eigenaar/naam.git
29artifacts/job-id/…
30releases/eigenaar/naam/tag/…
31work/pipeline/job/ tijdelijke clone voor een job
32ssh/host_ed25519 hostkey van de git-SSH
33```
34
35Geheimen in de database zijn versleuteld. Sessietokens van de auth-server staan als tekst in SQLite; de bestandsmachtiging van de database is de grens. Versleutelen van die sessies staat op de roadmap.
36
37## Auth
38
39De interface `auth.Provider` heeft `AuthorizeURL`, `Exchange`, `Extend` en `Logout`. `TimFalken` praat met auth.timfalken.com. `Dev` vult dezelfde interface lokaal, zonder wachtwoord, en mag niet aan op het productiedomein.
40
41Na de code-wissel bewaart BlueGit het bearer-token in de sessie. Korter dan zes uur voor het einde wordt `POST /api/session/extend` aangeroepen. Afmelden trekt het token in met `POST /api/logout`.
42
43Git en de API gebruiken een apart toegangstoken (`bg_…`) of, alleen tijdens een job, een job-token (`bgj_…`). Dat zijn geen wachtwoorden: ze worden één keer getoond, als hash bewaard, en zijn in te trekken. Het OAuth-token leeft 24 uur en is een slechte git-credential.
44
45Details en de eisen van de auth-server staan in [AUTH.md](AUTH.md).
46
47## Rechten
48
49`internal/access` is bewust los van HTTP en SQL. `Resolve` kiest de hoogste rol uit: installatiebeheerder, persoonlijke eigenaar, groepslid, rechtstreeks lid. `AuthorizeUpdate` keurt een pre-receive-regel goed. De hook is die functie, aangeroepen als `bluegit hook pre-receive`, met de rol en de patronen in de omgeving. Zonder die omgeving weigert de hook, zodat een push om de server heen niet slaagt.
50
51De installatiebeheerder is overal beheerder. Dat is handig op een machine van één persoon, en ruim als er later meer mensen op zitten. Zie de open vragen.
52
53## Web
54
55De pagina's zijn serverside HTML uit de binary. De router is de standaard `ServeMux` van Go 1.22. Een repository staat op `/{eigenaar}/{naam}`. Git staat op `/{eigenaar}/{naam}.git`. Vaste paden (`/login`, `/groups`, `/settings`, `/api`) winnen van die wildcard.
56
57Formulieren sturen een CSRF-token uit de sessie mee. De API gebruikt een bearer-token en geen CSRF.
58
59## Push naar pipeline
60
61Na een geslaagde smart-HTTP-push of SSH-push vergelijkt BlueGit de refs. Voor elke bijgewerkte branch leest het `blue-ci-cd.yml` op die commit. Ontbreekt het bestand, dan gebeurt er niets. Is het ongeldig, dan komt er een mislukte pipeline met de fout in het log, zodat de push zelf niet blokkeert. Jobs waarvan de `rules` niet kloppen, worden niet aangemaakt.
62
63De runner zet een job op `running`, kloont de commit naar een werkmap, haalt artifacts van eerdere jobs binnen, en start:
64
65```text
66docker run --rm --network <ci.network> -e NAAM …
67 -v werkmap:/workspace --entrypoint sh IMAGE /workspace/.bluegit-job.sh
68```
69
70`-e NAAM` zonder waarde laat Docker de variabele uit de omgeving van BlueGit overnemen. Daardoor blijft een meerregelige SSH-sleutel heel, en staat de waarde niet in de proceslijst. Het netwerk van de container is het gewone Docker-netwerk, niet het hostnetwerk.
71
72`CI_JOB_TOKEN` hoort bij die ene lopende job. De release-API eist dat het token bij deze repository hoort en dat de job nog loopt. Assets moeten al als artifact van een geslaagde job in dezelfde pipeline bestaan.
73
74## Webhooks
75
76Een gebeurtenis gaat naar de webhooks van de repository en, als de repository van een groep is, ook naar die van de groep. Een repository-webhook ziet repositorygeheimen. Een groep-webhook ziet alleen groepgeheimen. Een beschermd geheim gaat mee als de branch van de gebeurtenis beschermd is.
77
78Het branchfilter geldt alleen voor `push`. Andere gebeurtenissen negeren het. Een onbekend geheim of veld in het sjabloon is een fout en er gaat niets uit, zodat er geen webhook vertrekt met een leeg token.
79
80## Vertrouwensgrens
81
82De systeemgebruiker `bluegit` kan alles lezen wat op de schijf staat, inclusief geheimen (hij heeft `secret.key`). Mensen op de website kunnen dat niet, behalve een beheerder via het JSON-export dat de auth-server verplicht stelt. CI-jobs zien de geheimen die de regel van beschermde branches toelaat. Ze zien de Docker-socket niet.
83
84Webhooks mogen naar elk http(s)-adres, ook naar iets op het lokale netwerk. Dat is nodig voor een bot naast de mini-PC. Het is ook een manier om een intern adres te raken. Een allowlist staat op de roadmap.