BlueGit

timfa bluegit

Overview

Activity

NovDecJanFebMarAprMayJunJulAugSepOctNov

544 contributions in the last 12 months

LessMore

Commits, merge requests and comments.

bluegit
fix: houd één writeJSON voor de API
timfa project_87923614_bot_3aff574f6f98414b945a8799374f9092 · pushed by timfa · 3 weeks ago
a3dee03d History
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 Tims blauwe ster: assets/logo.svg.

BlueGit

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. Bestemmingen in privénetwerken worden geweigerd; het IP wordt bij het verbinden vastgezet.
  • 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. De besluiten 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
auth:
  mode: dev
  dev_user: tim
ssh:
  enabled: false
ci:
  enabled: false

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 het absolute pad in dat scherm. Zet je toch storage_path in dit bestand, dan moet dat pad absoluut zijn; het slaat het scherm over zolang de state-map nog geen keuze bewaart.

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 op een pad dat jij kiest. Maak die map beschrijfbaar voor de gebruiker bluegit. Er is geen standaardpad. 2. Kopieer /usr/share/bluegit/storage.conf.example naar /etc/systemd/system/bluegit.service.d/storage.conf en zet ReadWritePaths op die map. Zonder die drop-in blokkeert ProtectSystem schrijven buiten /var/lib/bluegit, en de schrijftest in het setup-scherm faalt. De database blijft in /var/lib/bluegit. 3. 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. 4. Zet het geheim in /etc/bluegit/client_secret (mode 0600) of in BLUEGIT_AUTH_CLIENT_SECRET via /etc/bluegit/secret.env. 5. 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. 6. systemctl daemon-reload && systemctl enable --now bluegit. De eerste aanmelding wordt installatiebeheerder en kiest het pad in het setup-scherm. Daar staat ook hoeveel ruimte vrij is. Git en CI doen niets tot dat pad opgeslagen is.

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. Een bestemming in een privénetwerk, of een naam die daarheen oplost, wordt geweigerd. Het IP van een publieke naam wordt vastgezet op het moment van verbinden, en elke redirect wordt opnieuw gekeurd.

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.