# 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/<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).
