BlueGit

timfa bluegit

Files

bluegit
README.md

BlueGit

BlueGit is Tims eigen git-platform, bedoeld voor git.timfalken.com op een mini-PC met Arch Linux. De repositories staan op een configureerbare schijf (de 4 TB-disk). Aanmelden gaat via auth.timfalken.com. Er is geen lokaal wachtwoord.

Het logo is een blauwe ster met het git-teken in het midden: assets/logo.svg.

Stack

Eén statische Go-binary, SQLite voor de metadata, de gewone git voor de objecten, en Docker alleen voor CI-jobs.

Die keuze houdt de mini-PC klein. Er is geen Postgres, geen Redis en geen aparte frontend-build. Git zelf doet smart HTTP; dat protocol opnieuw bouwen levert niets op. SQLite past bij één machine en één beheerder: de database is een bestand naast de repositories, op dezelfde schijf. Een kant-en-klaar product als Forgejo zou sneller een volle forge geven, maar niet deze auth-server, dit CI-bestand of dit webhookmodel.

Wat deze basis al doet

  • Aanmelden met de authorization-code-flow van auth.timfalken.com. De eerste ingelogde gebruiker wordt installatiebeheerder. is_admin van de auth-server geeft die rol niet, en de vlag geeft geen toegang tot andermans repositories, groepen of geheimen.
  • Repositories van een gebruiker of een groep, met de rollen alleen-lezen, ontwikkelaar en beheerder. De standaardbranch is master.
  • Git over HTTPS (smart HTTP) en SSH. Achter de ingress is HTTP plain, en de clone-URL gebruikt ssh.public_host en ssh.public_port. ssh.listen is de poort op de mini-PC.
  • Webinterface: bestanden, commits, branches, merge requests, pipelines, releases, leden, geheimen en webhooks.
  • blue-ci-cd.yml: stages, jobs, needs, rules, artifacts. Elke job in een eigen container.
  • Geheimen als omgevingsvariabelen. Beschermde geheimen alleen op een beschermde branch.
  • Releases op een commit, vanuit een pipeline met een job-token. Artifacts worden release-bestanden.
  • Webhooks op repository en groep, met presets voor Discord, Grok Bot en een generieke JSON-webhook.
  • Een PKGBUILD, een systemd-unit en packaging/install.sh.

Wat nog niet af is, staat in docs/ROADMAP.md. De vorm van het systeem staat in docs/ARCHITECTURE.md. De auth-koppeling staat in docs/AUTH.md. De ingress staat in docs/INGRESS.md. Besloten en nog open vragen staan in docs/VRAGEN.md.

Lokaal proberen

auth.mode: dev maakt een sessie zonder de auth-server. Dat is geen wachtwoord, en de configuratie weigert deze modus zodra base_url op git.timfalken.com wijst.

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

Open http://127.0.0.1:8080 en meld aan. Onder Account maak je een toegangstoken. Git gebruikt dat token als wachtwoord:

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

Installeren op Arch

Eerste keer met de hand, daarna kan de pipeline in blue-ci-cd.yml de binary vervangen.

sudo packaging/install.sh
# of, vanuit de repository:
cd packaging/arch && makepkg -si

Daarna:

1. Mount de 4 TB-schijf. Het mountpoint is nog niet gekozen. Maak de map voor BlueGit aan als de gebruiker bluegit. 2. Zet storage_path in /etc/bluegit/config.yml op die map. /mnt/storage/bluegit in het voorbeeld is geen besluit. 3. Kopieer /usr/share/bluegit/storage.conf.example naar /etc/systemd/system/bluegit.service.d/storage.conf en pas het pad aan. Zonder die drop-in blokkeert ProtectSystem schrijven buiten /var/lib/bluegit. De drop-in wordt niet geïnstalleerd, omdat een pad dat niet bestaat de dienst zou tegenhouden. 4. Registreer bij https://auth.timfalken.com/admin het domein git.timfalken.com met callback-pad /auth/callback. Het client_id is het domein. Het geheim verschijnt één keer. 5. Zet het geheim in /etc/bluegit/client_secret (mode 0600) of in BLUEGIT_AUTH_CLIENT_SECRET via /etc/bluegit/secret.env. 6. Zet de ingress op de andere machine. BlueGit zelf blijft plain HTTP. trusted_proxies is het adres van die ingress, base_url is https://git.timfalken.com, en ssh.public_port is de poort die gebruikers zien. Het voorbeeld staat in docs/INGRESS.md. 7. systemctl enable --now bluegit. De eerste aanmelding wordt installatiebeheerder.

SSH voor git luistert op ssh.listen (in het voorbeeld 0.0.0.0:2222), naast de SSH van het besturingssysteem. De hostkey komt de eerste keer in de opslagmap. De clone-URL gebruikt ssh.public_host en ssh.public_port, niet de bindpoort.

Rollen

Een repository hoort bij een gebruiker (die is beheerder) of bij een groep. Iemand kan ook rechtstreeks lid zijn. De hoogste rol telt.

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

Een ontwikkelaar ziet geheimen niet terug. Een job krijgt ze wel als omgevingsvariabele, anders kan CI er niets mee. Wie een pipeline mag starten, kan een onbeschermd geheim dus uitlezen via blue-ci-cd.yml. Markeer een geheim als beschermd als het alleen op een beschermde branch mee mag, en bescherm master.

De installatiebeheerder is geen beheerder van andermans repository. Geheimen, groepen en privérepositories blijven bij de leden.

CI, releases, webhooks

De specificatie staat in docs/CI.md. Kort: stages, jobs, image, script, needs, rules, artifacts. Elke job is docker run van dat image.

Een release maakt de pipeline zelf, met CI_JOB_TOKEN en CI_API_URL. Bestanden komen uit artifacts van een eerdere job in dezelfde pipeline, niet uit de request-body.

Webhooks hebben een URL-sjabloon, eigen headers en een body-sjabloon. {{secret.NAAM}} en {{event.summary}} worden bij het versturen ingevuld. Een push kan gefilterd worden op een exacte branch of op re: plus een reguliere expressie. Presets: discord, grok (JSON met een Authorization-header) en generic.

Zelf bijwerken

blue-ci-cd.yml test, bouwt een statische binary, maakt een release en kopieert die via SSH naar de host. Daar is geen apart deploy-kanaal voor. De eerste binary zet je neer met het pakket. Daarna zijn de geheimen DEPLOY_HOST, DEPLOY_USER, DEPLOY_PORT, DEPLOY_PATH en DEPLOY_SSH_KEY genoeg, als beschermde geheimen op een beschermde branch.

Tests

go test ./...

De kern zit in internal/access (rollen en beschermde branches), internal/ci (de parser en wanneer een job mag starten) en internal/webhook (filters en sjablonen). internal/server doet een ronde met een echte git push en controleert dat een ontwikkelaar geen geheim kan opslaan.

Licentie

MIT. Zie LICENSE.