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