BlueGit

timfa bluegit

Files

bluegit / docs / runner.md

runner.md

runner.md 20.3 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.22+ (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). 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 releases publiceren, zoals voorheen), 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.22+ (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).
113Het runner-token mag alleen de repo clonen van een job die die runner op
114dat moment draait. `CI_JOB_TOKEN` geeft alleen leestoegang tot de eigen
115repo (zie hieronder).
116
117## Globale runners
118
119Beheerders registreren onder **Beheer → Runner → Globale runners** (of
120`POST /api/v1/admin/runners/registration-token`, `bg admin runner token`)
121een runner die voor **alle repo's** beschikbaar is, publiek en privé, net
122als de ingebouwde runner. Registreren gaat met hetzelfde
123`bluegit-runner register --url … --token …`. Overzicht, hernoemen,
124pauzeren en verwijderen: in dezelfde tab, via `/api/v1/admin/runners[/{id}]`
125of `bg admin runner list|rename|pause|resume|delete|jobs`. Niet-beheerders
126krijgen `403`.
127
128**Volgorde**: globale runners → groeps-/account-runners en de
129BlueGit-runner in de bestaande volgorde. Een globale runner krijgt dus
130een job vóór de ingebouwde runner; pakt hij hem niet binnen 20 seconden
131op (of is hij offline/gepauzeerd), dan schuift de job door.
132
133**Security**: een globale runner krijgt jobs uit élke repo, dus ook de
134broncode en de geheimen van die jobs. Per job gaan alleen de geheimen van
135die job mee (repo/groep, met de bescherming voor beschermde refs), en het
136runner-token mag alleen de repo clonen van een job die hij op dat moment
137draait. Registreer alleen machines die je volledig vertrouwt; de UI, de
138API (`warning`) en `bg` tonen die waarschuwing bij het registreren.
139
140## Wat gebeurt er per job
141
142- **1.** Long-poll `POST /api/v1/runner/jobs/request` geeft de job: script, variabelen (incl. geheimen en `CI_JOB_TOKEN`), maskers, clone-URL, sha.
143- **2.** Clone via HTTPS met het runner-token, checkout van de sha.
144- **3.** Artifacts van eerdere jobs: `GET /api/v1/runner/jobs/{id}/inputs`.
145- **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).
146- **5.** Artifacts: `PUT /api/v1/runner/jobs/{id}/artifacts` (alleen de gedeclareerde paden).
147- **6.** `POST /api/v1/runner/jobs/{id}/finish`.
148
149Heartbeat: `POST /api/v1/runner/heartbeat` elke 30 s; online = contact in
150de laatste 90 s. De **cache** (`cache:`) blijft lokaal op de
151runnermachine in `work_dir/cache`.
152
153De job-UI en de API (`runner` in job-JSON: `{id, name, kind}`) tonen
154welke runner een job draaide.
155
156## Git en API vanuit een job (`CI_JOB_TOKEN`)
157
158Een job kan zonder eigen inlog bij de eigen repo, ook als die privé is:
159
160- `origin` in `/workspace` wijst naar `CI_PROJECT_URL.git` (ook bij de ingebouwde runner).
161- 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.
162- `git ls-remote origin`, `git fetch`, `git clone $CI_PROJECT_URL.git` werken dus gewoon (scripts zoals `next-version.sh` hoeven niets te veranderen).
163- 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*.
164- Niet: pushen, schrijven via de API (behalve releases publiceren, zoals voorheen), andere repo's, of iets na het einde van de job: het token vervalt dan.
165
166Pipelines hebben zo dezelfde bescherming als de repo: wie de repo niet
167mag lezen, ziet ook de pipelines niet, en het job-token komt niet verder
168dan de eigen repo.
169
170## Beheer via de API (en voor agents)
171
172Zelfde regels als de UI: account-endpoints alleen voor de eigenaar zelf,
173groepsendpoints alleen voor maintainers/eigenaar van de groep. Gebruik een
174access token (`bg_…`) met scope **`runners`** (alleen runnerbeheer) of
175`api`; `read_api` mag alleen lezen. Job-tokens (`CI_JOB_TOKEN`) en
176runner-tokens krijgen hier `401`.
177
178| Methode | Pad (account: `/api/v1/user`, groep: `/api/v1/groups/{pad}`) | |
179|---|---|---|
180| GET | `…/runners` | lijst: `id, name, status (online/offline/paused), online, paused, last_seen, version` |
181| POST | `…/runners/registration-token` | `{token, expires_at}`; het token staat alleen in deze response |
182| GET | `…/runners/{id}` | één runner |
183| PUT | `…/runners/{id}` | `{"name": "...", "paused": true}` (beide optioneel) |
184| POST | `…/runners/{id}/pause`, `…/runners/{id}/resume` | pauzeren/hervatten; gepauzeerd krijgt geen nieuwe jobs |
185| DELETE | `…/runners/{id}` | intrekken (token werkt meteen niet meer) |
186| GET | `…/runners/{id}/jobs?limit=20` | recente jobs (project alleen als je dat mag zien) |
187| GET/PUT | `/api/v1/user/runner-settings` | `{"preference": "builtin_first" \| "own_first"}` |
188| GET/PUT | `/api/v1/groups/{pad}/runner-settings` | `{"builtin_first": true}`; antwoord noemt ook `opted_in` |
189| 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) |
190
191### Volledige setup met alleen een token
192
193```sh
194export BLUEGIT_URL=https://git.timfalken.com BLUEGIT_TOKEN=bg_... # scope runners
195bg runner setup mijn-pc # token maken, sudo bluegit-runner register, wachten tot online
196# of los:
197BLUEGIT_RUNNER_REGISTRATION_TOKEN=$(bg runner token) \
198BLUEGIT_RUNNER_URL=$BLUEGIT_URL BLUEGIT_RUNNER_NAME=mijn-pc \
199 sudo -E bluegit-runner register
200bg runner wait mijn-pc && bg runner list
201```
202
203`bluegit-runner register` leest `BLUEGIT_RUNNER_REGISTRATION_TOKEN`,
204`BLUEGIT_RUNNER_URL` en `BLUEGIT_RUNNER_NAME` als de vlaggen ontbreken.
205
206## Webinterface
207
208Elke `bluegit-runner` heeft een eigen beheerscherm in de BlueGit-stijl, in
209het Nederlands, Engels, Duits en Frans (keuze rechtsboven, of `language` in
210de config).
211
212- **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`.
213- **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.
214- **Inhoud**:
215 - status: online/offline, versie, server-URL, laatste contact, en of de runner in BlueGit gepauzeerd is;
216 - hardware: CPU-kernen, geheugen en vrije schijf, met **aanbevelingen** (★) per instelling en een knop *Aanbevelingen toepassen*;
217 - **upgraden**: aantal lopende jobs en *veilig om te upgraden* als er niets loopt, plus **Pauzeren (aflopen)** / **Hervatten**;
218 - actieve en recente jobs (job, project, pipeline, image, duur);
219 - instellingen (hieronder) en image-presets;
220 - een docs-pagina op `/docs`.
221
222### Instellingen
223
224| instelling | standaard | wat |
225|---|---|---|
226| naam | hostname | naam in BlueGit en in de joblog; wordt bij opslaan (en elke heartbeat) naar de server gesynchroniseerd |
227| labels | — | eigen labels voor je overzicht |
228| jobs tegelijk | `concurrency` | 1–64, live aan te passen |
229| maximaal aantal gecachte images | 20 | images die de runner gebruikte; boven dit aantal gaan de langst ongebruikte weg |
230| maximale jobduur | — | begrenst de timeout uit de pipeline |
231| CPU's / geheugen / processen per job | geen limiet | `docker run --cpus`, `--memory`, `--pids-limit` |
232| schijfbudget | geen limiet | richtwaarde voor images, checkouts en cache samen |
233| pull-beleid | ophalen als het ontbreekt | `always` haalt gewone images elke job opnieuw op, `never` gebruikt alleen lokale images; presets worden altijd lokaal gebouwd |
234| werkmap na job verwijderen | aan | uit laat `work_dir/work/<job>` staan om te debuggen |
235| dangling images opruimen | aan | `docker image prune -f` na elke job |
236| maximale jobcache | 10 GB | oudste cachemappen eerst weg |
237
238**Aanbevelingen** gaan uit van ~2 kernen en ~2 GB per job, houden 1 kern en
2391 GB voor de host en rekenen ~10 GB schijf per job. Voorbeeld: 8 kernen,
24016 GB, 200 GB vrij → 3 jobs tegelijk, 2 CPU's en 5120 MB per job.
241
242### Image-presets
243
244Net als bij Steve (de ingebouwde runner): `image: bluegit/node` is geen
245apart image maar een Dockerfile die bij het eerste gebruik lokaal wordt
246gebouwd en hergebruikt zolang de Dockerfile gelijk blijft. De ingebouwde
247presets (`bluegit/base`, `node`, `python`, `go`, `rust`, `java`, `dotnet`)
248staan in de lijst. Eigen presets voeg je toe als:
249
250- **vast image** (`team/node` → `node:22-alpine`), of
251- **Dockerfile** (met optioneel een ander basis-image, `FROM`), of
252- alleen een ander **basis-image** voor een ingebouwde preset (bv. `bluegit/python` vanaf `python:3.13-slim`).
253
254### Pauze (drain)
255
256*Pauzeren* laat lopende jobs afmaken en pakt geen nieuwe op. De heartbeat
257meldt `draining`, dus BlueGit toont de runner als **gepauzeerd op de
258runner** (API: `status: "draining"`) en slaat hem over bij het verdelen:
259jobs gaan naar de volgende runner of blijven in de wachtrij. *Hervatten*
260zet alles terug. Dit staat los van pauzeren in BlueGit zelf
261(`…/runners/{id}/pause`); beide houden nieuwe jobs tegen.
262
263### Lokale API
264
265Met het beheertoken als Bearer-token (`Authorization: Bearer bgru_…`):
266
267| Methode | Pad | |
268|---|---|---|
269| GET | `/api/status` | status, hardware, aanbevelingen, `active_jobs`, `safe_to_upgrade` |
270| GET/PUT | `/api/settings` | alle instellingen als JSON (PUT: alleen de velden die je meestuurt veranderen) |
271| GET | `/api/jobs` | `active` en `recent` |
272| POST | `/api/pause`, `/api/resume` | pauze (drain) aan/uit |
273
274Veilig upgraden vanuit een script:
275
276```sh
277T=$(sudo cat /var/lib/bluegit-runner/ui-token); U=http://127.0.0.1:8765
278curl -fsS -X POST -H "Authorization: Bearer $T" $U/api/pause
279until curl -fsS -H "Authorization: Bearer $T" $U/api/status | grep -q '"safe_to_upgrade":true'; do sleep 10; done
280sudo pacman -Syu bluegit-runner # of je eigen installatie
281curl -fsS -X POST -H "Authorization: Bearer $T" $U/api/resume
282```
283
284## Ingebouwde runner
285
286De runner in het BlueGit-proces (Steve, `runner.name`) heeft hetzelfde
287scherm voor **sitebeheerders** op **/admin/runner** (menu *Runner*):
288dezelfde instellingen, aanbevelingen voor de server, eigen presets (naast
289`ci.presets` uit `config.yml`), opruimbeleid, pauze en het overzicht van
290actieve jobs. Instellingen staan in `runner-settings.json` in de statemap
291en gelden meteen. De API (token van een beheerder, scope `runners` of
292`api`):
293
294| Methode | Pad | |
295|---|---|---|
296| GET | `/api/v1/admin/runner/status` | status, hardware, aanbevelingen, `safe_to_upgrade` |
297| GET/PUT | `/api/v1/admin/runner/settings` | instellingen |
298| GET | `/api/v1/admin/runner/jobs` | actieve en recente jobs |
299| POST | `/api/v1/admin/runner/pause`, `/resume` | drain aan/uit |
300
301Niet-beheerders krijgen `403`. **Pauze en self-update**: de self-update
302wacht alleen op jobs die echt *running* zijn. Een gepauzeerde ingebouwde
303runner start niets nieuws, dus de update gaat door zodra de lopende jobs
304klaar zijn; wachtende jobs blijven `queued` (of gaan naar een eigen
305runner) en starten na het hervatten. Na een herstart blijft de pauze staan.
306
307## Security en isolatie
308
309- 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.
310- 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).
311- 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.
312- Geheimen uit de job worden in de log gemaskeerd, ook op de runner.
313- De service draait met `NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome` en `PrivateTmp`; schrijven kan alleen in `/var/lib/bluegit-runner`.
314- De webinterface luistert standaard op localhost, vraagt het beheertoken, gebruikt een `HttpOnly`/`SameSite=Strict`-cookie en CSRF-velden.
315
316## Online, offline en wegvallen
317
318- Heartbeat elke **30 s**; **online** = contact in de laatste **90 s**.
319- Een offline runner krijgt geen jobs; zijn trede wordt overgeslagen.
320- 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).
321- Een herstart van de service tijdens een job: de job mislukt zo (na de 5 minuten); pauzeer daarom eerst (zie *Veilig upgraden* hierboven).
322
323## Verwijderen of vervangen
324
325- **Intrekken**: in BlueGit bij de runner *Intrekken* (of `DELETE …/runners/{id}`). Het token werkt meteen niet meer; een lopende job mislukt.
326- **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.
327- **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`.
328- **Opnieuw registreren** op dezelfde machine: `register` overschrijft `url`, `token` en `name` in de config; de rest blijft.
329
330## Problemen
331
332| Symptoom | Oorzaak en oplossing |
333|---|---|
334| 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). |
335| `cannot reach BlueGit: … 401` | Het runner-token is ingetrokken of onbekend: opnieuw registreren. |
336| `registration failed (403)` | Registratietoken verlopen (24 u) of al gebruikt: maak een nieuwe. |
337| 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`? |
338| `permission denied` op de Docker-socket | Na `usermod -aG docker` de service herstarten. |
339| 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. |
340| 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. |
341| Image niet gevonden met pull-beleid *nooit* | Haal het image handmatig op (`docker pull`) of zet het beleid terug. |
342| Preset bouwt niet | De bouwlog staat in de joblog (`Building image preset …`); test de Dockerfile met `docker build`. |
343| Schijf vol | Verlaag *maximaal aantal images* en *maximale jobcache*, zet *dangling images opruimen* aan, of `docker system prune`. |
344| 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. |
345| Naam in BlueGit klopt niet | Zet de naam in de webinterface; die wint en gaat met de volgende heartbeat (≤ 30 s) mee. |
346
347Handige commando's:
348
349```sh
350journalctl -u bluegit-runner -f
351sudo -u bluegit-runner docker info
352sudo bluegit-runner ui-token
353bluegit-runner version
354```
355
356Runnerbeheer via de BlueGit-API voor agents staat ook in [agents.md](agents.md#runners).