# 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.26+ (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?

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

**Repo van een account** — voorkeur onder Instellingen → Runners:

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

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

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

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

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

## Globale runners

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

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

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

## Wat gebeurt er per job

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

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

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

## Git en API vanuit een job (`CI_JOB_TOKEN`)

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

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

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

## Beheer via de API (en voor agents)

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

| 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 (elk groepslid; je runner krijgt alleen jobs uit repo's die je zelf mag lezen) |

### 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/<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/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://<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:

```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).
