BlueGit

timfa bluegit

Files

bluegit / docs / runner.md

runner.md

runner.md 18.6 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?

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 maintainers 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 maintainer telt alleen zolang die maintainer is. 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).

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 (maintainer)

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