BlueGit

timfa bluegit

Files

bluegit / docs / runner.md

runner.md

runner.md 21.1 KiB Download Raw

bluegit-runner — aparte CI-runner

bluegit-runner draait BlueGit CI-jobs op je eigen machine, in Docker, net als de ingebouwde runner. De runner maakt alleen uitgaande HTTPS-verbindingen naar BlueGit (long-poll); er hoeft geen poort open. De ingebouwde BlueGit-runner blijft gewoon bestaan.

Netwerk

De runner maakt alleen uitgaande verbindingen:

  • HTTPS (poort 443) naar de BlueGit-server, voor heartbeat, jobs, logs en artifacts;
  • internet voor wat de jobs zelf ophalen (Docker-images, packages).

Op de runnermachine hoeft geen enkele poort open, ook niet achter NAT of een thuisrouter. Een proxy werkt via de gewone HTTPS_PROXY-variabele in de service-omgeving. De eigen webinterface luistert standaard alleen op 127.0.0.1 (zie Webinterface).

Installeren (Arch / AUR)

yay -S bluegit-runner        # of: git clone https://aur.archlinux.org/bluegit-runner.git && makepkg -si

Het pakket maakt de systeemgebruiker bluegit-runner (lid van docker), installeert bluegit-runner.service en zet die aan. De service start zodra /etc/bluegit-runner/config.yml bestaat; een upgrade herstart hem.

Installeren buiten Arch (binary + systemd)

Nodig: Docker, git en Go 1.26+ (alleen om te bouwen).

git clone https://git.timfalken.com/timfa/bluegit.git && cd bluegit
go build -trimpath -ldflags "-X main.version=$(date +%Y%m%d%H%M%S)" -o bluegit-runner ./cmd/bluegit-runner
sudo install -Dm755 bluegit-runner /usr/bin/bluegit-runner
sudo install -Dm644 packaging/runner/bluegit-runner.service /usr/lib/systemd/system/bluegit-runner.service
sudo install -Dm644 packaging/runner/sysusers.conf /usr/lib/sysusers.d/bluegit-runner.conf
sudo install -Dm644 packaging/runner/tmpfiles.conf /usr/lib/tmpfiles.d/bluegit-runner.conf
sudo systemd-sysusers && sudo systemd-tmpfiles --create
sudo usermod -aG docker bluegit-runner
sudo systemctl daemon-reload && sudo systemctl enable bluegit-runner

Daarna registreren. Zonder systemd: bluegit-runner run --config pad/naar/config.yml als een gebruiker die Docker mag gebruiken.

Registreren

  • 1. In BlueGit: Instellingen → Runners → Nieuw registratietoken voor een account-runner, of Groep → Instellingen → Runners voor een groepsrunner (maintainer). Het token (bgrr_…) is 24 uur geldig, eenmalig, en je ziet het één keer.
  • 2. Op de machine:
   sudo bluegit-runner register --url https://git.timfalken.com --token bgrr_... [--name mijn-pc]

De runner krijgt een eigen runner-token (bgr_…); de server bewaart alleen de hash. Het token staat in /etc/bluegit-runner/config.yml (mode 0600, eigenaar bluegit-runner). register start de service.

  • 3. In de UI staat de runner nu als online. Intrekken kan daar ook; het token werkt dan meteen niet meer.

Het registratietoken mag ook via BLUEGIT_RUNNER_REGISTRATION_TOKEN.

Config

/etc/bluegit-runner/config.yml:

sleutelstandaard
url—BlueGit-adres (door register)
token—runner-token (door register)
namehostnamenaam in de UI en in de joblog
dockerdockerdocker-binary
gitgitgit-binary
work_dir/var/lib/bluegit-runnerwerkmappen en cache
networkbridgedocker-netwerk voor jobs zonder services
concurrency1jobs tegelijk (startwaarde; daarna via de webinterface)
ui_listen127.0.0.1:8765adres van de webinterface; off zet hem uit
language(browser)standaardtaal van de webinterface: en, nl, de, fr

Wat je in de webinterface instelt, staat in work_dir/settings.json (schrijfbaar voor de service; /etc is dat onder ProtectSystem=strict niet).

Welke runner krijgt een job?

Globale runners (door beheerders geregistreerd, zie hieronder) staan voor elke repo vooraan: globale runners → de volgorde hieronder (die eindigt of begint met de BlueGit-runner). Is er geen globale runner online, dan wordt die trede meteen overgeslagen.

Repo van een account — voorkeur onder Instellingen → Runners:

  • Mijn runners alleen als de BlueGit-runner niet meteen beschikbaar is (standaard): BlueGit-runner → eigen runners.
  • Eigen runners eerst: eigen runners → BlueGit-runner.

Repo van een groep: groepsrunners → account-runners van groepsleden die toestemming gaven (Groep → Instellingen → Runners → "Mijn runners toestaan") → BlueGit-runner. Met Probeer BlueGit runner eerst staat de BlueGit-runner vooraan.

Een trede zonder online runner wordt meteen overgeslagen. Pakt geen runner de job binnen 20 seconden op, of is de BlueGit-runner vol, dan gaat de job naar de volgende trede (en daarna weer rond). Een runner die midden in een job 5 minuten niets van zich laat horen, laat de job mislukken met runner_system_failure (retry-regels gelden).

Privacy: een account-runner krijgt alleen jobs uit repo's die zijn eigenaar mag lezen; een groepsrunner alleen uit repo's van die groep. Toestemming van een groepslid telt alleen zolang die lid is, en alleen voor repo's die dat lid zelf mag lezen (bij elke toewijzing opnieuw gecontroleerd).

Beschermde branches en tags: een job op een beschermde branch, of op een tag die op een beschermd tagpatroon past, krijgt beschermde geheimen (een tag telt nooit via een branchpatroon). Die job draait alleen op de BlueGit-runner, globale runners, groepsrunners en account-runners van gebruikers die maintainer (of eigenaar) van die repo zijn, of instance-admin. Opt-in-runners van gewone leden/developers worden voor zo'n job overgeslagen: de job valt door naar de volgende toegestane trede (uiteindelijk de BlueGit-runner), nooit naar een niet-toegestane runner. Het joblog meldt welke runners zijn overgeslagen. De controle gebeurt bij elke toewijzing (ook bij retry en herplanning), dus ingetrokken rechten gelden meteen. Voor niet-beschermde branches verandert er niets. Het runner-token mag alleen de repo clonen van een job die die runner op dat moment draait. CI_JOB_TOKEN geeft alleen leestoegang tot de eigen repo (zie hieronder).

Globale runners

Beheerders registreren onder Beheer → Runner → Globale runners (of POST /api/v1/admin/runners/registration-token, bg admin runner token) een runner die voor alle repo's beschikbaar is, publiek en privé, net als de ingebouwde runner. Registreren gaat met hetzelfde bluegit-runner register --url … --token …. Overzicht, hernoemen, pauzeren en verwijderen: in dezelfde tab, via /api/v1/admin/runners[/{id}] of bg admin runner list|rename|pause|resume|delete|jobs. Niet-beheerders krijgen 403.

Volgorde: globale runners → groeps-/account-runners en de BlueGit-runner in de bestaande volgorde. Een globale runner krijgt dus een job vóór de ingebouwde runner; pakt hij hem niet binnen 20 seconden op (of is hij offline/gepauzeerd), dan schuift de job door.

Security: een globale runner krijgt jobs uit élke repo, dus ook de broncode en de geheimen van die jobs. Per job gaan alleen de geheimen van die job mee (repo/groep, met de bescherming voor beschermde refs), en het runner-token mag alleen de repo clonen van een job die hij op dat moment draait. Registreer alleen machines die je volledig vertrouwt; de UI, de API (warning) en bg tonen die waarschuwing bij het registreren.

Wat gebeurt er per job

  • 1. Long-poll POST /api/v1/runner/jobs/request geeft de job: script, variabelen (incl. geheimen en CI_JOB_TOKEN), maskers, clone-URL, sha.
  • 2. Clone via HTTPS met het runner-token, checkout van de sha.
  • 3. Artifacts van eerdere jobs: GET /api/v1/runner/jobs/{id}/inputs.
  • 4. Container draaien (zelfde code als de ingebouwde runner, incl. image presets en services); log elke seconde naar POST /api/v1/runner/jobs/{id}/log (antwoord {"cancel":true} stopt de job).
  • 5. Artifacts: PUT /api/v1/runner/jobs/{id}/artifacts (alleen de gedeclareerde paden).
  • 6. POST /api/v1/runner/jobs/{id}/finish.

Heartbeat: POST /api/v1/runner/heartbeat elke 30 s; online = contact in de laatste 90 s. De cache (cache:) blijft lokaal op de runnermachine in work_dir/cache.

De job-UI en de API (runner in job-JSON: {id, name, kind}) tonen welke runner een job draaide.

Git en API vanuit een job (CI_JOB_TOKEN)

Een job kan zonder eigen inlog bij de eigen repo, ook als die privé is:

  • origin in /workspace wijst naar CI_PROJECT_URL.git (ook bij de ingebouwde runner).
  • De runner zet via GIT_CONFIG_COUNT/GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n een http.<projecturl>.extraHeader met Authorization: Bearer $CI_JOB_TOKEN, alleen voor de URL van dit project. Er komt geen bestand in de container, dus het werkt in elk image (ook bluegit/base) zolang git ≥ 2.31 is.
  • git ls-remote origin, git fetch, git clone $CI_PROJECT_URL.git werken dus gewoon (scripts zoals next-version.sh hoeven niets te veranderen).
  • De API: GET-routes onder /api/v1/…/{owner}/{repo} van de eigen repo met Authorization: Bearer $CI_JOB_TOKEN (of PRIVATE-TOKEN). Leesrechten, zoals een lid met de rol readonly.
  • Niet: pushen, schrijven via de API (behalve een release publiceren: POST /repos/…/releases maakt een tag, POST /repos/…/releases/{tag}/assets publiceert bij een tag die al bestaat), andere repo's, of iets na het einde van de job: het token vervalt dan.

Pipelines hebben zo dezelfde bescherming als de repo: wie de repo niet mag lezen, ziet ook de pipelines niet, en het job-token komt niet verder dan de eigen repo.

Beheer via de API (en voor agents)

Zelfde regels als de UI: account-endpoints alleen voor de eigenaar zelf, groepsendpoints alleen voor maintainers/eigenaar van de groep. Gebruik een access token (bg_…) met scope runners (alleen runnerbeheer) of api; read_api mag alleen lezen. Job-tokens (CI_JOB_TOKEN) en runner-tokens krijgen hier 401.

MethodePad (account: /api/v1/user, groep: /api/v1/groups/{pad})
GET…/runnerslijst: id, name, status (online/offline/paused), online, paused, last_seen, version
POST…/runners/registration-token{token, expires_at}; het token staat alleen in deze response
GET…/runners/{id}één runner
PUT…/runners/{id}{"name": "...", "paused": true} (beide optioneel)
POST…/runners/{id}/pause, …/runners/{id}/resumepauzeren/hervatten; gepauzeerd krijgt geen nieuwe jobs
DELETE…/runners/{id}intrekken (token werkt meteen niet meer)
GET…/runners/{id}/jobs?limit=20recente jobs (project alleen als je dat mag zien)
GET/PUT/api/v1/user/runner-settings`{"preference": "builtin_first" \"own_first"}`
GET/PUT/api/v1/groups/{pad}/runner-settings{"builtin_first": true}; antwoord noemt ook opted_in
GET/PUT/api/v1/groups/{pad}/runner-optin{"enabled": true} — alleen je eigen toestemming (elk groepslid; je runner krijgt alleen jobs uit repo's die je zelf mag lezen)

Volledige setup met alleen een token

export BLUEGIT_URL=https://git.timfalken.com BLUEGIT_TOKEN=bg_...   # scope runners
bg runner setup mijn-pc                 # token maken, sudo bluegit-runner register, wachten tot online
# of los:
BLUEGIT_RUNNER_REGISTRATION_TOKEN=$(bg runner token) \
BLUEGIT_RUNNER_URL=$BLUEGIT_URL BLUEGIT_RUNNER_NAME=mijn-pc \
  sudo -E bluegit-runner register
bg runner wait mijn-pc && bg runner list

bluegit-runner register leest BLUEGIT_RUNNER_REGISTRATION_TOKEN, BLUEGIT_RUNNER_URL en BLUEGIT_RUNNER_NAME als de vlaggen ontbreken.

Webinterface

Elke bluegit-runner heeft een eigen beheerscherm in de BlueGit-stijl, in het Nederlands, Engels, Duits en Frans (keuze rechtsboven, of language in de config).

  • Adres: standaard http://127.0.0.1:8765, alleen lokaal. Wijzig ui_listen (bv. 0.0.0.0:8765 op een vertrouwd netwerk) of gebruik een SSH-tunnel: ssh -L 8765:127.0.0.1:8765 runnermachine.
  • Toegang: een beheertoken (bgru_…) dat bij de eerste start lokaal in work_dir/ui-token (mode 0600) wordt gemaakt. Het komt nooit in de logs; toon het op de machine zelf met sudo bluegit-runner ui-token. register noemt dat commando ook.
  • Inhoud:
  • status: online/offline, versie, server-URL, laatste contact, en of de runner in BlueGit gepauzeerd is;
  • hardware: CPU-kernen, geheugen en vrije schijf, met aanbevelingen (★) per instelling en een knop Aanbevelingen toepassen;
  • upgraden: aantal lopende jobs en veilig om te upgraden als er niets loopt, plus Pauzeren (aflopen) / Hervatten;
  • actieve en recente jobs (job, project, pipeline, image, duur);
  • instellingen (hieronder) en image-presets;
  • een docs-pagina op /docs.

Instellingen

instellingstandaardwat
naamhostnamenaam in BlueGit en in de joblog; wordt bij opslaan (en elke heartbeat) naar de server gesynchroniseerd
labels—eigen labels voor je overzicht
jobs tegelijkconcurrency1–64, live aan te passen
maximaal aantal gecachte images20images die de runner gebruikte; boven dit aantal gaan de langst ongebruikte weg
maximale jobduur—begrenst de timeout uit de pipeline
CPU's / geheugen / processen per jobgeen limietdocker run --cpus, --memory, --pids-limit
schijfbudgetgeen limietrichtwaarde voor images, checkouts en cache samen
pull-beleidophalen als het ontbreektalways haalt gewone images elke job opnieuw op, never gebruikt alleen lokale images; presets worden altijd lokaal gebouwd
werkmap na job verwijderenaanuit laat work_dir/work/<job> staan om te debuggen
dangling images opruimenaandocker image prune -f na elke job
maximale jobcache10 GBoudste cachemappen eerst weg

Aanbevelingen gaan uit van ~2 kernen en ~2 GB per job, houden 1 kern en 1 GB voor de host en rekenen ~10 GB schijf per job. Voorbeeld: 8 kernen, 16 GB, 200 GB vrij → 3 jobs tegelijk, 2 CPU's en 5120 MB per job.

Image-presets

Net als bij Steve (de ingebouwde runner): image: bluegit/node is geen apart image maar een Dockerfile die bij het eerste gebruik lokaal wordt gebouwd en hergebruikt zolang de Dockerfile gelijk blijft. De ingebouwde presets (bluegit/base, node, python, go, rust, java, dotnet) staan in de lijst. Eigen presets voeg je toe als:

  • vast image (team/node → node:22-alpine), of
  • Dockerfile (met optioneel een ander basis-image, FROM), of
  • alleen een ander basis-image voor een ingebouwde preset (bv. bluegit/python vanaf python:3.13-slim).

Pauze (drain)

Pauzeren laat lopende jobs afmaken en pakt geen nieuwe op. De heartbeat meldt draining, dus BlueGit toont de runner als gepauzeerd op de runner (API: status: "draining") en slaat hem over bij het verdelen: jobs gaan naar de volgende runner of blijven in de wachtrij. Hervatten zet alles terug. Dit staat los van pauzeren in BlueGit zelf (…/runners/{id}/pause); beide houden nieuwe jobs tegen.

Lokale API

Met het beheertoken als Bearer-token (Authorization: Bearer bgru_…):

MethodePad
GET/api/statusstatus, hardware, aanbevelingen, active_jobs, safe_to_upgrade
GET/PUT/api/settingsalle instellingen als JSON (PUT: alleen de velden die je meestuurt veranderen)
GET/api/jobsactive en recent
POST/api/pause, /api/resumepauze (drain) aan/uit

Veilig upgraden vanuit een script:

T=$(sudo cat /var/lib/bluegit-runner/ui-token); U=http://127.0.0.1:8765
curl -fsS -X POST -H "Authorization: Bearer $T" $U/api/pause
until curl -fsS -H "Authorization: Bearer $T" $U/api/status | grep -q '"safe_to_upgrade":true'; do sleep 10; done
sudo pacman -Syu bluegit-runner   # of je eigen installatie
curl -fsS -X POST -H "Authorization: Bearer $T" $U/api/resume

Ingebouwde runner

De runner in het BlueGit-proces (Steve, runner.name) heeft hetzelfde scherm voor sitebeheerders op /admin/runner (menu Runner): dezelfde instellingen, aanbevelingen voor de server, eigen presets (naast ci.presets uit config.yml), opruimbeleid, pauze en het overzicht van actieve jobs. Instellingen staan in runner-settings.json in de statemap en gelden meteen. De API (token van een beheerder, scope runners of api):

MethodePad
GET/api/v1/admin/runner/statusstatus, hardware, aanbevelingen, safe_to_upgrade
GET/PUT/api/v1/admin/runner/settingsinstellingen
GET/api/v1/admin/runner/jobsactieve en recente jobs
POST/api/v1/admin/runner/pause, /resumedrain aan/uit

Niet-beheerders krijgen 403. Pauze en self-update: de self-update wacht alleen op jobs die echt running zijn. Een gepauzeerde ingebouwde runner start niets nieuws, dus de update gaat door zodra de lopende jobs klaar zijn; wachtende jobs blijven queued (of gaan naar een eigen runner) en starten na het hervatten. Na een herstart blijft de pauze staan.

Security en isolatie

  • Elke job draait in een eigen Docker-container (docker run --rm) met de checkout op /workspace; services in een eigen netwerk per job. Limieten per job (CPU, geheugen, processen) zet je in de webinterface.
  • Docker-toegang is root-equivalent op die machine: geef een runner alleen jobs uit repo's die je vertrouwt (account-runners krijgen alleen jobs van repo's van hun eigenaar, groepsrunners alleen van hun groep).
  • Het runner-token (bgr_…) staat alleen in config.yml (0600); de server bewaart alleen de hash. Het mag alleen de repo clonen van een job die die runner op dat moment draait, en gaat via de omgeving naar git (niet in de proceslijst). Het registratietoken (bgrr_…) is eenmalig en 24 uur geldig.
  • Geheimen uit de job worden in de log gemaskeerd, ook op de runner.
  • De service draait met NoNewPrivileges, ProtectSystem=strict, ProtectHome en PrivateTmp; schrijven kan alleen in /var/lib/bluegit-runner.
  • De webinterface luistert standaard op localhost, vraagt het beheertoken, gebruikt een HttpOnly/SameSite=Strict-cookie en CSRF-velden.

Online, offline en wegvallen

  • Heartbeat elke 30 s; online = contact in de laatste 90 s.
  • Een offline runner krijgt geen jobs; zijn trede wordt overgeslagen.
  • Valt een runner midden in een job weg (stroom, netwerk, crash), dan zet BlueGit de job na 5 minuten zonder contact op mislukt met runner_system_failure. Staat retry op runner_system_failure of always, dan wordt hij opnieuw ingepland (ook op een andere runner).
  • Een herstart van de service tijdens een job: de job mislukt zo (na de 5 minuten); pauzeer daarom eerst (zie Veilig upgraden hierboven).

Verwijderen of vervangen

  • Intrekken: in BlueGit bij de runner Intrekken (of DELETE …/runners/{id}). Het token werkt meteen niet meer; een lopende job mislukt.
  • Machine weg: sudo systemctl disable --now bluegit-runner, sudo pacman -Rns bluegit-runner (of de bestanden weghalen) en de runner in BlueGit intrekken. /var/lib/bluegit-runner bevat cache, presets en het UI-token.
  • Vervangen (nieuwe machine, zelfde naam): nieuw registratietoken, register op de nieuwe machine, de oude intrekken. Je instellingen kun je meenemen door settings.json te kopiëren of via PUT /api/settings.
  • Opnieuw registreren op dezelfde machine: register overschrijft url, token en name in de config; de rest blijft.

Problemen

SymptoomOorzaak en oplossing
Runner blijft offlinejournalctl -u bluegit-runner -f. Komt de heartbeat niet aan, test curl -I https://<server>/healthz vanaf de machine (DNS, proxy, firewall uitgaand 443).
cannot reach BlueGit: … 401Het runner-token is ingetrokken of onbekend: opnieuw registreren.
registration failed (403)Registratietoken verlopen (24 u) of al gebruikt: maak een nieuwe.
Jobs mislukken met runner_system_failure: docker … is not availablesudo -u bluegit-runner docker info moet werken; zit de gebruiker in groep docker en draait docker.service?
permission denied op de Docker-socketNa usermod -aG docker de service herstarten.
Clone mislukt (403)Het runner-token mag alleen de repo van zijn eigen lopende job clonen; komt dit toch, kijk of de job niet al afgebroken is.
Job blijft In wachtrijRunner gepauzeerd (lokaal of in BlueGit), jobs tegelijk vol, of de runner hoort niet bij deze repo/groep. Bekijk de runnervolgorde hierboven.
Image niet gevonden met pull-beleid nooitHaal het image handmatig op (docker pull) of zet het beleid terug.
Preset bouwt nietDe bouwlog staat in de joblog (Building image preset …); test de Dockerfile met docker build.
Schijf volVerlaag maximaal aantal images en maximale jobcache, zet dangling images opruimen aan, of docker system prune.
Webinterface opent nietKijk ui_listen na, en of een ander programma de poort gebruikt (ss -ltnp). Token kwijt: sudo bluegit-runner ui-token; nieuw token: verwijder work_dir/ui-token en herstart.
Naam in BlueGit klopt nietZet de naam in de webinterface; die wint en gaat met de volgende heartbeat (≤ 30 s) mee.

Handige commando's:

journalctl -u bluegit-runner -f
sudo -u bluegit-runner docker info
sudo bluegit-runner ui-token
bluegit-runner version

Runnerbeheer via de BlueGit-API voor agents staat ook in agents.md.

Source
1# bluegit-runner — aparte CI-runner
2
3`bluegit-runner` draait BlueGit CI-jobs op je eigen machine, in Docker,
4net als de ingebouwde runner. De runner maakt alleen **uitgaande**
5HTTPS-verbindingen naar BlueGit (long-poll); er hoeft geen poort open.
6De ingebouwde BlueGit-runner blijft gewoon bestaan.
7
8## Netwerk
9
10De runner maakt alleen **uitgaande** verbindingen:
11
12- HTTPS (poort 443) naar de BlueGit-server, voor heartbeat, jobs, logs en artifacts;
13- internet voor wat de jobs zelf ophalen (Docker-images, packages).
14
15Op de runnermachine hoeft **geen enkele poort open**, ook niet achter NAT
16of een thuisrouter. Een proxy werkt via de gewone `HTTPS_PROXY`-variabele
17in de service-omgeving. De eigen webinterface luistert standaard alleen op
18`127.0.0.1` (zie [Webinterface](#webinterface)).
19
20## Installeren (Arch / AUR)
21
22```sh
23yay -S bluegit-runner # of: git clone https://aur.archlinux.org/bluegit-runner.git && makepkg -si
24```
25
26Het pakket maakt de systeemgebruiker `bluegit-runner` (lid van `docker`),
27installeert `bluegit-runner.service` en zet die aan. De service start
28zodra `/etc/bluegit-runner/config.yml` bestaat; een upgrade herstart hem.
29
30## Installeren buiten Arch (binary + systemd)
31
32Nodig: Docker, git en Go 1.26+ (alleen om te bouwen).
33
34```sh
35git clone https://git.timfalken.com/timfa/bluegit.git && cd bluegit
36go build -trimpath -ldflags "-X main.version=$(date +%Y%m%d%H%M%S)" -o bluegit-runner ./cmd/bluegit-runner
37sudo install -Dm755 bluegit-runner /usr/bin/bluegit-runner
38sudo install -Dm644 packaging/runner/bluegit-runner.service /usr/lib/systemd/system/bluegit-runner.service
39sudo install -Dm644 packaging/runner/sysusers.conf /usr/lib/sysusers.d/bluegit-runner.conf
40sudo install -Dm644 packaging/runner/tmpfiles.conf /usr/lib/tmpfiles.d/bluegit-runner.conf
41sudo systemd-sysusers && sudo systemd-tmpfiles --create
42sudo usermod -aG docker bluegit-runner
43sudo systemctl daemon-reload && sudo systemctl enable bluegit-runner
44```
45
46Daarna [registreren](#registreren). Zonder systemd: `bluegit-runner run --config pad/naar/config.yml`
47als een gebruiker die Docker mag gebruiken.
48
49## Registreren
50
51- **1.** In BlueGit: **Instellingen → Runners → Nieuw registratietoken** voor een account-runner, of **Groep → Instellingen → Runners** voor een groepsrunner (maintainer). Het token (`bgrr_…`) is 24 uur geldig, eenmalig, en je ziet het één keer.
52- **2.** Op de machine:
53
54 ```sh
55 sudo bluegit-runner register --url https://git.timfalken.com --token bgrr_... [--name mijn-pc]
56 ```
57
58 De runner krijgt een eigen runner-token (`bgr_…`); de server bewaart
59 alleen de hash. Het token staat in `/etc/bluegit-runner/config.yml`
60 (mode 0600, eigenaar `bluegit-runner`). `register` start de service.
61- **3.** In de UI staat de runner nu als **online**. Intrekken kan daar ook; het token werkt dan meteen niet meer.
62
63Het registratietoken mag ook via `BLUEGIT_RUNNER_REGISTRATION_TOKEN`.
64
65## Config
66
67`/etc/bluegit-runner/config.yml`:
68
69| sleutel | standaard | |
70|---|---|---|
71| `url` | — | BlueGit-adres (door register) |
72| `token` | — | runner-token (door register) |
73| `name` | hostname | naam in de UI en in de joblog |
74| `docker` | `docker` | docker-binary |
75| `git` | `git` | git-binary |
76| `work_dir` | `/var/lib/bluegit-runner` | werkmappen en cache |
77| `network` | `bridge` | docker-netwerk voor jobs zonder services |
78| `concurrency` | `1` | jobs tegelijk (startwaarde; daarna via de webinterface) |
79| `ui_listen` | `127.0.0.1:8765` | adres van de webinterface; `off` zet hem uit |
80| `language` | (browser) | standaardtaal van de webinterface: `en`, `nl`, `de`, `fr` |
81
82Wat je in de webinterface instelt, staat in `work_dir/settings.json`
83(schrijfbaar voor de service; `/etc` is dat onder `ProtectSystem=strict` niet).
84
85## Welke runner krijgt een job?
86
87**Globale runners** (door beheerders geregistreerd, zie hieronder) staan
88voor elke repo vooraan: globale runners → de volgorde hieronder (die
89eindigt of begint met de BlueGit-runner). Is er geen globale runner
90online, dan wordt die trede meteen overgeslagen.
91
92**Repo van een account** — voorkeur onder Instellingen → Runners:
93
94- *Mijn runners alleen als de BlueGit-runner niet meteen beschikbaar is* (standaard): BlueGit-runner → eigen runners.
95- *Eigen runners eerst*: eigen runners → BlueGit-runner.
96
97**Repo van een groep**: groepsrunners → account-runners van groepsleden
98die toestemming gaven (Groep → Instellingen → Runners → "Mijn runners
99toestaan") → BlueGit-runner. Met **Probeer BlueGit runner eerst** staat
100de BlueGit-runner vooraan.
101
102Een trede zonder online runner wordt meteen overgeslagen. Pakt geen
103runner de job binnen 20 seconden op, of is de BlueGit-runner vol, dan
104gaat de job naar de volgende trede (en daarna weer rond). Een runner die
105midden in een job 5 minuten niets van zich laat horen, laat de job
106mislukken met `runner_system_failure` (retry-regels gelden).
107
108**Privacy**: een account-runner krijgt alleen jobs uit repo's die zijn
109eigenaar mag lezen; een groepsrunner alleen uit repo's van die groep.
110Toestemming van een groepslid telt alleen zolang die lid is, en
111alleen voor repo's die dat lid zelf mag lezen (bij elke toewijzing
112opnieuw gecontroleerd).
113
114**Beschermde branches en tags**: een job op een beschermde branch, of op
115een tag die op een beschermd tagpatroon past, krijgt beschermde geheimen
116(een tag telt nooit via een branchpatroon). Die job draait alleen op de BlueGit-runner, globale
117runners, groepsrunners en account-runners van gebruikers die maintainer
118(of eigenaar) van die repo zijn, of instance-admin. Opt-in-runners van
119gewone leden/developers worden voor zo'n job overgeslagen: de job valt door
120naar de volgende toegestane trede (uiteindelijk de BlueGit-runner), nooit
121naar een niet-toegestane runner. Het joblog meldt welke runners zijn
122overgeslagen. De controle gebeurt bij elke toewijzing (ook bij retry en
123herplanning), dus ingetrokken rechten gelden meteen. Voor niet-beschermde
124branches verandert er niets.
125Het runner-token mag alleen de repo clonen van een job die die runner op
126dat moment draait. `CI_JOB_TOKEN` geeft alleen leestoegang tot de eigen
127repo (zie hieronder).
128
129## Globale runners
130
131Beheerders registreren onder **Beheer → Runner → Globale runners** (of
132`POST /api/v1/admin/runners/registration-token`, `bg admin runner token`)
133een runner die voor **alle repo's** beschikbaar is, publiek en privé, net
134als de ingebouwde runner. Registreren gaat met hetzelfde
135`bluegit-runner register --url … --token …`. Overzicht, hernoemen,
136pauzeren en verwijderen: in dezelfde tab, via `/api/v1/admin/runners[/{id}]`
137of `bg admin runner list|rename|pause|resume|delete|jobs`. Niet-beheerders
138krijgen `403`.
139
140**Volgorde**: globale runners → groeps-/account-runners en de
141BlueGit-runner in de bestaande volgorde. Een globale runner krijgt dus
142een job vóór de ingebouwde runner; pakt hij hem niet binnen 20 seconden
143op (of is hij offline/gepauzeerd), dan schuift de job door.
144
145**Security**: een globale runner krijgt jobs uit élke repo, dus ook de
146broncode en de geheimen van die jobs. Per job gaan alleen de geheimen van
147die job mee (repo/groep, met de bescherming voor beschermde refs), en het
148runner-token mag alleen de repo clonen van een job die hij op dat moment
149draait. Registreer alleen machines die je volledig vertrouwt; de UI, de
150API (`warning`) en `bg` tonen die waarschuwing bij het registreren.
151
152## Wat gebeurt er per job
153
154- **1.** Long-poll `POST /api/v1/runner/jobs/request` geeft de job: script, variabelen (incl. geheimen en `CI_JOB_TOKEN`), maskers, clone-URL, sha.
155- **2.** Clone via HTTPS met het runner-token, checkout van de sha.
156- **3.** Artifacts van eerdere jobs: `GET /api/v1/runner/jobs/{id}/inputs`.
157- **4.** Container draaien (zelfde code als de ingebouwde runner, incl. image presets en services); log elke seconde naar `POST /api/v1/runner/jobs/{id}/log` (antwoord `{"cancel":true}` stopt de job).
158- **5.** Artifacts: `PUT /api/v1/runner/jobs/{id}/artifacts` (alleen de gedeclareerde paden).
159- **6.** `POST /api/v1/runner/jobs/{id}/finish`.
160
161Heartbeat: `POST /api/v1/runner/heartbeat` elke 30 s; online = contact in
162de laatste 90 s. De **cache** (`cache:`) blijft lokaal op de
163runnermachine in `work_dir/cache`.
164
165De job-UI en de API (`runner` in job-JSON: `{id, name, kind}`) tonen
166welke runner een job draaide.
167
168## Git en API vanuit een job (`CI_JOB_TOKEN`)
169
170Een job kan zonder eigen inlog bij de eigen repo, ook als die privé is:
171
172- `origin` in `/workspace` wijst naar `CI_PROJECT_URL.git` (ook bij de ingebouwde runner).
173- De runner zet via `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_n`/`GIT_CONFIG_VALUE_n` een `http.<projecturl>.extraHeader` met `Authorization: Bearer $CI_JOB_TOKEN`, alleen voor de URL van dit project. Er komt geen bestand in de container, dus het werkt in elk image (ook `bluegit/base`) zolang git ≥ 2.31 is.
174- `git ls-remote origin`, `git fetch`, `git clone $CI_PROJECT_URL.git` werken dus gewoon (scripts zoals `next-version.sh` hoeven niets te veranderen).
175- De API: `GET`-routes onder `/api/v1/…/{owner}/{repo}` van de eigen repo met `Authorization: Bearer $CI_JOB_TOKEN` (of `PRIVATE-TOKEN`). Leesrechten, zoals een lid met de rol *readonly*.
176- Niet: pushen, schrijven via de API (behalve een release publiceren: `POST /repos/…/releases` maakt een tag, `POST /repos/…/releases/{tag}/assets` publiceert bij een tag die al bestaat), andere repo's, of iets na het einde van de job: het token vervalt dan.
177
178Pipelines hebben zo dezelfde bescherming als de repo: wie de repo niet
179mag lezen, ziet ook de pipelines niet, en het job-token komt niet verder
180dan de eigen repo.
181
182## Beheer via de API (en voor agents)
183
184Zelfde regels als de UI: account-endpoints alleen voor de eigenaar zelf,
185groepsendpoints alleen voor maintainers/eigenaar van de groep. Gebruik een
186access token (`bg_…`) met scope **`runners`** (alleen runnerbeheer) of
187`api`; `read_api` mag alleen lezen. Job-tokens (`CI_JOB_TOKEN`) en
188runner-tokens krijgen hier `401`.
189
190| Methode | Pad (account: `/api/v1/user`, groep: `/api/v1/groups/{pad}`) | |
191|---|---|---|
192| GET | `…/runners` | lijst: `id, name, status (online/offline/paused), online, paused, last_seen, version` |
193| POST | `…/runners/registration-token` | `{token, expires_at}`; het token staat alleen in deze response |
194| GET | `…/runners/{id}` | één runner |
195| PUT | `…/runners/{id}` | `{"name": "...", "paused": true}` (beide optioneel) |
196| POST | `…/runners/{id}/pause`, `…/runners/{id}/resume` | pauzeren/hervatten; gepauzeerd krijgt geen nieuwe jobs |
197| DELETE | `…/runners/{id}` | intrekken (token werkt meteen niet meer) |
198| GET | `…/runners/{id}/jobs?limit=20` | recente jobs (project alleen als je dat mag zien) |
199| GET/PUT | `/api/v1/user/runner-settings` | `{"preference": "builtin_first" \| "own_first"}` |
200| GET/PUT | `/api/v1/groups/{pad}/runner-settings` | `{"builtin_first": true}`; antwoord noemt ook `opted_in` |
201| GET/PUT | `/api/v1/groups/{pad}/runner-optin` | `{"enabled": true}` — alleen je eigen toestemming (elk groepslid; je runner krijgt alleen jobs uit repo's die je zelf mag lezen) |
202
203### Volledige setup met alleen een token
204
205```sh
206export BLUEGIT_URL=https://git.timfalken.com BLUEGIT_TOKEN=bg_... # scope runners
207bg runner setup mijn-pc # token maken, sudo bluegit-runner register, wachten tot online
208# of los:
209BLUEGIT_RUNNER_REGISTRATION_TOKEN=$(bg runner token) \
210BLUEGIT_RUNNER_URL=$BLUEGIT_URL BLUEGIT_RUNNER_NAME=mijn-pc \
211 sudo -E bluegit-runner register
212bg runner wait mijn-pc && bg runner list
213```
214
215`bluegit-runner register` leest `BLUEGIT_RUNNER_REGISTRATION_TOKEN`,
216`BLUEGIT_RUNNER_URL` en `BLUEGIT_RUNNER_NAME` als de vlaggen ontbreken.
217
218## Webinterface
219
220Elke `bluegit-runner` heeft een eigen beheerscherm in de BlueGit-stijl, in
221het Nederlands, Engels, Duits en Frans (keuze rechtsboven, of `language` in
222de config).
223
224- **Adres**: standaard `http://127.0.0.1:8765`, alleen lokaal. Wijzig `ui_listen` (bv. `0.0.0.0:8765` op een vertrouwd netwerk) of gebruik een SSH-tunnel: `ssh -L 8765:127.0.0.1:8765 runnermachine`.
225- **Toegang**: een beheertoken (`bgru_…`) dat bij de eerste start lokaal in `work_dir/ui-token` (mode 0600) wordt gemaakt. Het komt nooit in de logs; toon het op de machine zelf met `sudo bluegit-runner ui-token`. `register` noemt dat commando ook.
226- **Inhoud**:
227 - status: online/offline, versie, server-URL, laatste contact, en of de runner in BlueGit gepauzeerd is;
228 - hardware: CPU-kernen, geheugen en vrije schijf, met **aanbevelingen** (★) per instelling en een knop *Aanbevelingen toepassen*;
229 - **upgraden**: aantal lopende jobs en *veilig om te upgraden* als er niets loopt, plus **Pauzeren (aflopen)** / **Hervatten**;
230 - actieve en recente jobs (job, project, pipeline, image, duur);
231 - instellingen (hieronder) en image-presets;
232 - een docs-pagina op `/docs`.
233
234### Instellingen
235
236| instelling | standaard | wat |
237|---|---|---|
238| naam | hostname | naam in BlueGit en in de joblog; wordt bij opslaan (en elke heartbeat) naar de server gesynchroniseerd |
239| labels | — | eigen labels voor je overzicht |
240| jobs tegelijk | `concurrency` | 1–64, live aan te passen |
241| maximaal aantal gecachte images | 20 | images die de runner gebruikte; boven dit aantal gaan de langst ongebruikte weg |
242| maximale jobduur | — | begrenst de timeout uit de pipeline |
243| CPU's / geheugen / processen per job | geen limiet | `docker run --cpus`, `--memory`, `--pids-limit` |
244| schijfbudget | geen limiet | richtwaarde voor images, checkouts en cache samen |
245| pull-beleid | ophalen als het ontbreekt | `always` haalt gewone images elke job opnieuw op, `never` gebruikt alleen lokale images; presets worden altijd lokaal gebouwd |
246| werkmap na job verwijderen | aan | uit laat `work_dir/work/<job>` staan om te debuggen |
247| dangling images opruimen | aan | `docker image prune -f` na elke job |
248| maximale jobcache | 10 GB | oudste cachemappen eerst weg |
249
250**Aanbevelingen** gaan uit van ~2 kernen en ~2 GB per job, houden 1 kern en
2511 GB voor de host en rekenen ~10 GB schijf per job. Voorbeeld: 8 kernen,
25216 GB, 200 GB vrij → 3 jobs tegelijk, 2 CPU's en 5120 MB per job.
253
254### Image-presets
255
256Net als bij Steve (de ingebouwde runner): `image: bluegit/node` is geen
257apart image maar een Dockerfile die bij het eerste gebruik lokaal wordt
258gebouwd en hergebruikt zolang de Dockerfile gelijk blijft. De ingebouwde
259presets (`bluegit/base`, `node`, `python`, `go`, `rust`, `java`, `dotnet`)
260staan in de lijst. Eigen presets voeg je toe als:
261
262- **vast image** (`team/node` → `node:22-alpine`), of
263- **Dockerfile** (met optioneel een ander basis-image, `FROM`), of
264- alleen een ander **basis-image** voor een ingebouwde preset (bv. `bluegit/python` vanaf `python:3.13-slim`).
265
266### Pauze (drain)
267
268*Pauzeren* laat lopende jobs afmaken en pakt geen nieuwe op. De heartbeat
269meldt `draining`, dus BlueGit toont de runner als **gepauzeerd op de
270runner** (API: `status: "draining"`) en slaat hem over bij het verdelen:
271jobs gaan naar de volgende runner of blijven in de wachtrij. *Hervatten*
272zet alles terug. Dit staat los van pauzeren in BlueGit zelf
273(`…/runners/{id}/pause`); beide houden nieuwe jobs tegen.
274
275### Lokale API
276
277Met het beheertoken als Bearer-token (`Authorization: Bearer bgru_…`):
278
279| Methode | Pad | |
280|---|---|---|
281| GET | `/api/status` | status, hardware, aanbevelingen, `active_jobs`, `safe_to_upgrade` |
282| GET/PUT | `/api/settings` | alle instellingen als JSON (PUT: alleen de velden die je meestuurt veranderen) |
283| GET | `/api/jobs` | `active` en `recent` |
284| POST | `/api/pause`, `/api/resume` | pauze (drain) aan/uit |
285
286Veilig upgraden vanuit een script:
287
288```sh
289T=$(sudo cat /var/lib/bluegit-runner/ui-token); U=http://127.0.0.1:8765
290curl -fsS -X POST -H "Authorization: Bearer $T" $U/api/pause
291until curl -fsS -H "Authorization: Bearer $T" $U/api/status | grep -q '"safe_to_upgrade":true'; do sleep 10; done
292sudo pacman -Syu bluegit-runner # of je eigen installatie
293curl -fsS -X POST -H "Authorization: Bearer $T" $U/api/resume
294```
295
296## Ingebouwde runner
297
298De runner in het BlueGit-proces (Steve, `runner.name`) heeft hetzelfde
299scherm voor **sitebeheerders** op **/admin/runner** (menu *Runner*):
300dezelfde instellingen, aanbevelingen voor de server, eigen presets (naast
301`ci.presets` uit `config.yml`), opruimbeleid, pauze en het overzicht van
302actieve jobs. Instellingen staan in `runner-settings.json` in de statemap
303en gelden meteen. De API (token van een beheerder, scope `runners` of
304`api`):
305
306| Methode | Pad | |
307|---|---|---|
308| GET | `/api/v1/admin/runner/status` | status, hardware, aanbevelingen, `safe_to_upgrade` |
309| GET/PUT | `/api/v1/admin/runner/settings` | instellingen |
310| GET | `/api/v1/admin/runner/jobs` | actieve en recente jobs |
311| POST | `/api/v1/admin/runner/pause`, `/resume` | drain aan/uit |
312
313Niet-beheerders krijgen `403`. **Pauze en self-update**: de self-update
314wacht alleen op jobs die echt *running* zijn. Een gepauzeerde ingebouwde
315runner start niets nieuws, dus de update gaat door zodra de lopende jobs
316klaar zijn; wachtende jobs blijven `queued` (of gaan naar een eigen
317runner) en starten na het hervatten. Na een herstart blijft de pauze staan.
318
319## Security en isolatie
320
321- Elke job draait in een **eigen Docker-container** (`docker run --rm`) met de checkout op `/workspace`; services in een eigen netwerk per job. Limieten per job (CPU, geheugen, processen) zet je in de webinterface.
322- Docker-toegang is root-equivalent op die machine: geef een runner alleen jobs uit repo's die je vertrouwt (account-runners krijgen alleen jobs van repo's van hun eigenaar, groepsrunners alleen van hun groep).
323- Het **runner-token** (`bgr_…`) staat alleen in `config.yml` (0600); de server bewaart alleen de **hash**. Het mag alleen de repo clonen van een job die die runner op dat moment draait, en gaat via de omgeving naar git (niet in de proceslijst). Het registratietoken (`bgrr_…`) is eenmalig en 24 uur geldig.
324- Geheimen uit de job worden in de log gemaskeerd, ook op de runner.
325- De service draait met `NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome` en `PrivateTmp`; schrijven kan alleen in `/var/lib/bluegit-runner`.
326- De webinterface luistert standaard op localhost, vraagt het beheertoken, gebruikt een `HttpOnly`/`SameSite=Strict`-cookie en CSRF-velden.
327
328## Online, offline en wegvallen
329
330- Heartbeat elke **30 s**; **online** = contact in de laatste **90 s**.
331- Een offline runner krijgt geen jobs; zijn trede wordt overgeslagen.
332- Valt een runner **midden in een job** weg (stroom, netwerk, crash), dan zet BlueGit de job na **5 minuten** zonder contact op mislukt met `runner_system_failure`. Staat `retry` op `runner_system_failure` of `always`, dan wordt hij opnieuw ingepland (ook op een andere runner).
333- Een herstart van de service tijdens een job: de job mislukt zo (na de 5 minuten); pauzeer daarom eerst (zie *Veilig upgraden* hierboven).
334
335## Verwijderen of vervangen
336
337- **Intrekken**: in BlueGit bij de runner *Intrekken* (of `DELETE …/runners/{id}`). Het token werkt meteen niet meer; een lopende job mislukt.
338- **Machine weg**: `sudo systemctl disable --now bluegit-runner`, `sudo pacman -Rns bluegit-runner` (of de bestanden weghalen) en de runner in BlueGit intrekken. `/var/lib/bluegit-runner` bevat cache, presets en het UI-token.
339- **Vervangen** (nieuwe machine, zelfde naam): nieuw registratietoken, `register` op de nieuwe machine, de oude intrekken. Je instellingen kun je meenemen door `settings.json` te kopiëren of via `PUT /api/settings`.
340- **Opnieuw registreren** op dezelfde machine: `register` overschrijft `url`, `token` en `name` in de config; de rest blijft.
341
342## Problemen
343
344| Symptoom | Oorzaak en oplossing |
345|---|---|
346| Runner blijft *offline* | `journalctl -u bluegit-runner -f`. Komt de heartbeat niet aan, test `curl -I https://<server>/healthz` vanaf de machine (DNS, proxy, firewall uitgaand 443). |
347| `cannot reach BlueGit: … 401` | Het runner-token is ingetrokken of onbekend: opnieuw registreren. |
348| `registration failed (403)` | Registratietoken verlopen (24 u) of al gebruikt: maak een nieuwe. |
349| Jobs mislukken met `runner_system_failure: docker … is not available` | `sudo -u bluegit-runner docker info` moet werken; zit de gebruiker in groep `docker` en draait `docker.service`? |
350| `permission denied` op de Docker-socket | Na `usermod -aG docker` de service herstarten. |
351| Clone mislukt (`403`) | Het runner-token mag alleen de repo van zijn eigen lopende job clonen; komt dit toch, kijk of de job niet al afgebroken is. |
352| Job blijft *In wachtrij* | Runner gepauzeerd (lokaal of in BlueGit), `jobs tegelijk` vol, of de runner hoort niet bij deze repo/groep. Bekijk de runnervolgorde hierboven. |
353| Image niet gevonden met pull-beleid *nooit* | Haal het image handmatig op (`docker pull`) of zet het beleid terug. |
354| Preset bouwt niet | De bouwlog staat in de joblog (`Building image preset …`); test de Dockerfile met `docker build`. |
355| Schijf vol | Verlaag *maximaal aantal images* en *maximale jobcache*, zet *dangling images opruimen* aan, of `docker system prune`. |
356| Webinterface opent niet | Kijk `ui_listen` na, en of een ander programma de poort gebruikt (`ss -ltnp`). Token kwijt: `sudo bluegit-runner ui-token`; nieuw token: verwijder `work_dir/ui-token` en herstart. |
357| Naam in BlueGit klopt niet | Zet de naam in de webinterface; die wint en gaat met de volgende heartbeat (≤ 30 s) mee. |
358
359Handige commando's:
360
361```sh
362journalctl -u bluegit-runner -f
363sudo -u bluegit-runner docker info
364sudo bluegit-runner ui-token
365bluegit-runner version
366```
367
368Runnerbeheer via de BlueGit-API voor agents staat ook in [agents.md](agents.md#runners).