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