# 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](https://auth.timfalken.com). Er is geen lokaal wachtwoord. Het logo is Tims blauwe ster: [`assets/logo.svg`](assets/logo.svg). ![BlueGit](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. 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](docs/ROADMAP.md). De vorm van het systeem staat in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). De auth-koppeling staat in [docs/AUTH.md](docs/AUTH.md). De ingress staat in [docs/INGRESS.md](docs/INGRESS.md). De besluiten staan in [docs/VRAGEN.md](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. ```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 ``` 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. ```shell 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: ```shell 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`](blue-ci-cd.yml) de binary vervangen. ```shell 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](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. | 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 | 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](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`](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 ```shell 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](LICENSE).