BlueGit

timfa bluegit

Files

bluegit / README.md

README.md

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

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.
  • Repositories van een gebruiker of een groep, met de rollen alleen-lezen, ontwikkelaar en beheerder.
  • Git over HTTPS (smart HTTP). SSH staat in de code en achter ssh.enabled, op poort 2222.
  • 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.

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, bijvoorbeeld op /mnt/storage, en maak /mnt/storage/bluegit aan als de gebruiker bluegit. 2. Zet storage_path in /etc/bluegit/config.yml op die map. 3. Kopieer /usr/share/bluegit/storage.conf.example naar /etc/systemd/system/bluegit.service.d/storage.conf. Zonder die drop-in blokkeert ProtectSystem schrijven buiten /var/lib/bluegit. 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 een reverse proxy voor HTTPS. Caddy is genoeg:

git.timfalken.com {
  reverse_proxy 127.0.0.1:8080
}

7. systemctl enable --now bluegit. De eerste aanmelding wordt installatiebeheerder.

SSH voor git luistert op 0.0.0.0:2222, naast de SSH van het besturingssysteem. De hostkey komt de eerste keer in de opslagmap.

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 main.

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. Dat is een keuze voor deze basis; zeg het als het anders moet.

Source
1# BlueGit
2
3BlueGit 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.
4
5Het logo is een blauwe ster met het git-teken in het midden: [`assets/logo.svg`](assets/logo.svg).
6
7## Stack
8
9Eén statische Go-binary, SQLite voor de metadata, de gewone `git` voor de objecten, en Docker alleen voor CI-jobs.
10
11Die 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.
12
13## Wat deze basis al doet
14
15- Aanmelden met de authorization-code-flow van auth.timfalken.com. De eerste ingelogde gebruiker wordt installatiebeheerder.
16- Repositories van een gebruiker of een groep, met de rollen alleen-lezen, ontwikkelaar en beheerder.
17- Git over HTTPS (smart HTTP). SSH staat in de code en achter `ssh.enabled`, op poort 2222.
18- Webinterface: bestanden, commits, branches, merge requests, pipelines, releases, leden, geheimen en webhooks.
19- `blue-ci-cd.yml`: stages, jobs, `needs`, `rules`, artifacts. Elke job in een eigen container.
20- Geheimen als omgevingsvariabelen. Beschermde geheimen alleen op een beschermde branch.
21- Releases op een commit, vanuit een pipeline met een job-token. Artifacts worden release-bestanden.
22- Webhooks op repository en groep, met presets voor Discord, Grok Bot en een generieke JSON-webhook.
23- Een PKGBUILD, een systemd-unit en `packaging/install.sh`.
24
25Wat 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).
26
27## Lokaal proberen
28
29`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.
30
31```yaml
32base_url: http://127.0.0.1:8080
33listen: 127.0.0.1:8080
34storage_path: ./data
35auth:
36 mode: dev
37 dev_user: tim
38ssh:
39 enabled: false
40ci:
41 enabled: false
42```
43
44```shell
45go build -o bluegit ./cmd/bluegit
46./bluegit serve --config bluegit.yml
47```
48
49Open http://127.0.0.1:8080 en meld aan. Onder Account maak je een toegangstoken. Git gebruikt dat token als wachtwoord:
50
51```shell
52git clone http://tim:bg_…@127.0.0.1:8080/tim/demo.git
53```
54
55## Installeren op Arch
56
57Eerste keer met de hand, daarna kan de pipeline in [`blue-ci-cd.yml`](blue-ci-cd.yml) de binary vervangen.
58
59```shell
60sudo packaging/install.sh
61# of, vanuit de repository:
62cd packaging/arch && makepkg -si
63```
64
65Daarna:
66
671. Mount de 4 TB-schijf, bijvoorbeeld op `/mnt/storage`, en maak `/mnt/storage/bluegit` aan als de gebruiker `bluegit`.
682. Zet `storage_path` in `/etc/bluegit/config.yml` op die map.
693. Kopieer `/usr/share/bluegit/storage.conf.example` naar `/etc/systemd/system/bluegit.service.d/storage.conf`. Zonder die drop-in blokkeert `ProtectSystem` schrijven buiten `/var/lib/bluegit`.
704. 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.
715. Zet het geheim in `/etc/bluegit/client_secret` (mode `0600`) of in `BLUEGIT_AUTH_CLIENT_SECRET` via `/etc/bluegit/secret.env`.
726. Zet een reverse proxy voor HTTPS. Caddy is genoeg:
73
74```caddy
75git.timfalken.com {
76 reverse_proxy 127.0.0.1:8080
77}
78```
79
807. `systemctl enable --now bluegit`. De eerste aanmelding wordt installatiebeheerder.
81
82SSH voor git luistert op `0.0.0.0:2222`, naast de SSH van het besturingssysteem. De hostkey komt de eerste keer in de opslagmap.
83
84## Rollen
85
86Een repository hoort bij een gebruiker (die is beheerder) of bij een groep. Iemand kan ook rechtstreeks lid zijn. De hoogste rol telt.
87
88| Rol | Lezen | Schrijven op een gewone branch | Beschermde branch | Geheimen, webhooks, leden, verwijderen |
89| --- | --- | --- | --- | --- |
90| Alleen lezen | ja | nee | nee | nee |
91| Ontwikkelaar | ja | ja | nee | nee |
92| Beheerder | ja | ja | ja | ja |
93
94Een 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 `main`.
95
96## CI, releases, webhooks
97
98De 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.
99
100Een 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.
101
102Webhooks 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`.
103
104## Zelf bijwerken
105
106[`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.
107
108## Tests
109
110```shell
111go test ./...
112```
113
114De 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.
115
116## Licentie
117
118MIT. Dat is een keuze voor deze basis; zeg het als het anders moet.