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

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

Andere systemen: `go build -o /usr/bin/bluegit-runner ./cmd/bluegit-runner`
en kopieer de bestanden uit `packaging/runner/` naar systemd
(`bluegit-runner.service`, `sysusers.d`, `tmpfiles.d`).

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

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

## Problemen

```sh
journalctl -u bluegit-runner -f
sudo -u bluegit-runner docker info   # moet werken (groep docker)
```
