# 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](#webinterface)). ## Installeren (Arch / AUR) ```sh 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). ```sh 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](#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: ```sh 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/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. ## 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 ```sh 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 | 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/` 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/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_…`): | 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: ```sh 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 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 | Symptoom | Oorzaak en oplossing | |---|---| | Runner blijft *offline* | `journalctl -u bluegit-runner -f`. Komt de heartbeat niet aan, test `curl -I https:///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: ```sh 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](agents.md#runners).