BlueGit

timfa bluegit

Files

bluegit / docs / runner.md

runner.md

runner.md 6.3 KiB Download Raw

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)

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:

   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:

sleutelstandaard
url—BlueGit-adres (door register)
token—runner-token (door register)
namehostnamenaam in de UI en in de joblog
dockerdockerdocker-binary
gitgitgit-binary
work_dir/var/lib/bluegit-runnerwerkmappen en cache
networkbridgedocker-netwerk voor jobs zonder services
concurrency1jobs 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.

MethodePad (account: /api/v1/user, groep: /api/v1/groups/{pad})
GET…/runnerslijst: 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}/resumepauzeren/hervatten; gepauzeerd krijgt geen nieuwe jobs
DELETE…/runners/{id}intrekken (token werkt meteen niet meer)
GET…/runners/{id}/jobs?limit=20recente 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

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

journalctl -u bluegit-runner -f
sudo -u bluegit-runner docker info   # moet werken (groep docker)
Source
1# bluegit-runner — aparte CI-runner
2
3`bluegit-runner` draait BlueGit CI-jobs op je eigen machine, in Docker,
4net als de ingebouwde runner. De runner maakt alleen **uitgaande**
5HTTPS-verbindingen naar BlueGit (long-poll); er hoeft geen poort open.
6De ingebouwde BlueGit-runner blijft gewoon bestaan.
7
8## Installeren (Arch / AUR)
9
10```sh
11yay -S bluegit-runner # of: git clone https://aur.archlinux.org/bluegit-runner.git && makepkg -si
12```
13
14Het pakket maakt de systeemgebruiker `bluegit-runner` (lid van `docker`),
15installeert `bluegit-runner.service` en zet die aan. De service start
16zodra `/etc/bluegit-runner/config.yml` bestaat; een upgrade herstart hem.
17
18Andere systemen: `go build -o /usr/bin/bluegit-runner ./cmd/bluegit-runner`
19en kopieer de bestanden uit `packaging/runner/` naar systemd
20(`bluegit-runner.service`, `sysusers.d`, `tmpfiles.d`).
21
22## Registreren
23
241. In BlueGit: **Instellingen → Runners → Nieuw registratietoken** voor een
25 account-runner, of **Groep → Instellingen → Runners** voor een
26 groepsrunner (maintainer). Het token (`bgrr_…`) is 24 uur geldig,
27 eenmalig, en je ziet het één keer.
282. Op de machine:
29
30 ```sh
31 sudo bluegit-runner register --url https://git.timfalken.com --token bgrr_... [--name mijn-pc]
32 ```
33
34 De runner krijgt een eigen runner-token (`bgr_…`); de server bewaart
35 alleen de hash. Het token staat in `/etc/bluegit-runner/config.yml`
36 (mode 0600, eigenaar `bluegit-runner`). `register` start de service.
373. In de UI staat de runner nu als **online**. Intrekken kan daar ook;
38 het token werkt dan meteen niet meer.
39
40Het registratietoken mag ook via `BLUEGIT_RUNNER_REGISTRATION_TOKEN`.
41
42## Config
43
44`/etc/bluegit-runner/config.yml`:
45
46| sleutel | standaard | |
47|---|---|---|
48| `url` | — | BlueGit-adres (door register) |
49| `token` | — | runner-token (door register) |
50| `name` | hostname | naam in de UI en in de joblog |
51| `docker` | `docker` | docker-binary |
52| `git` | `git` | git-binary |
53| `work_dir` | `/var/lib/bluegit-runner` | werkmappen en cache |
54| `network` | `bridge` | docker-netwerk voor jobs zonder services |
55| `concurrency` | `1` | jobs tegelijk |
56
57## Welke runner krijgt een job?
58
59**Repo van een account** — voorkeur onder Instellingen → Runners:
60
61- *Mijn runners alleen als de BlueGit-runner niet meteen beschikbaar is*
62 (standaard): BlueGit-runner → eigen runners.
63- *Eigen runners eerst*: eigen runners → BlueGit-runner.
64
65**Repo van een groep**: groepsrunners → account-runners van maintainers
66die toestemming gaven (Groep → Instellingen → Runners → "Mijn runners
67toestaan") → BlueGit-runner. Met **Probeer BlueGit runner eerst** staat
68de BlueGit-runner vooraan.
69
70Een trede zonder online runner wordt meteen overgeslagen. Pakt geen
71runner de job binnen 20 seconden op, of is de BlueGit-runner vol, dan
72gaat de job naar de volgende trede (en daarna weer rond). Een runner die
73midden in een job 5 minuten niets van zich laat horen, laat de job
74mislukken met `runner_system_failure` (retry-regels gelden).
75
76**Privacy**: een account-runner krijgt alleen jobs uit repo's die zijn
77eigenaar mag lezen; een groepsrunner alleen uit repo's van die groep.
78Toestemming van een maintainer telt alleen zolang die maintainer is.
79Het runner-token mag alleen de repo clonen van een job die die runner op
80dat moment draait. De rechten van `CI_JOB_TOKEN` zijn ongewijzigd.
81
82## Wat gebeurt er per job
83
841. Long-poll `POST /api/v1/runner/jobs/request` geeft de job: script,
85 variabelen (incl. geheimen en `CI_JOB_TOKEN`), maskers, clone-URL, sha.
862. Clone via HTTPS met het runner-token, checkout van de sha.
873. Artifacts van eerdere jobs: `GET /api/v1/runner/jobs/{id}/inputs`.
884. Container draaien (zelfde code als de ingebouwde runner, incl. image
89 presets en services); log elke seconde naar
90 `POST /api/v1/runner/jobs/{id}/log` (antwoord `{"cancel":true}` stopt de job).
915. Artifacts: `PUT /api/v1/runner/jobs/{id}/artifacts` (alleen de gedeclareerde paden).
926. `POST /api/v1/runner/jobs/{id}/finish`.
93
94Heartbeat: `POST /api/v1/runner/heartbeat` elke 30 s; online = contact in
95de laatste 90 s. De **cache** (`cache:`) blijft lokaal op de
96runnermachine in `work_dir/cache`.
97
98De job-UI en de API (`runner` in job-JSON: `{id, name, kind}`) tonen
99welke runner een job draaide.
100
101## Beheer via de API (en voor agents)
102
103Zelfde regels als de UI: account-endpoints alleen voor de eigenaar zelf,
104groepsendpoints alleen voor maintainers/eigenaar van de groep. Gebruik een
105access token (`bg_…`) met scope **`runners`** (alleen runnerbeheer) of
106`api`; `read_api` mag alleen lezen. Job-tokens (`CI_JOB_TOKEN`) en
107runner-tokens krijgen hier `401`.
108
109| Methode | Pad (account: `/api/v1/user`, groep: `/api/v1/groups/{pad}`) | |
110|---|---|---|
111| GET | `…/runners` | lijst: `id, name, status (online/offline/paused), online, paused, last_seen, version` |
112| POST | `…/runners/registration-token` | `{token, expires_at}`; het token staat alleen in deze response |
113| GET | `…/runners/{id}` | één runner |
114| PUT | `…/runners/{id}` | `{"name": "...", "paused": true}` (beide optioneel) |
115| POST | `…/runners/{id}/pause`, `…/runners/{id}/resume` | pauzeren/hervatten; gepauzeerd krijgt geen nieuwe jobs |
116| DELETE | `…/runners/{id}` | intrekken (token werkt meteen niet meer) |
117| GET | `…/runners/{id}/jobs?limit=20` | recente jobs (project alleen als je dat mag zien) |
118| GET/PUT | `/api/v1/user/runner-settings` | `{"preference": "builtin_first" \| "own_first"}` |
119| GET/PUT | `/api/v1/groups/{pad}/runner-settings` | `{"builtin_first": true}`; antwoord noemt ook `opted_in` |
120| GET/PUT | `/api/v1/groups/{pad}/runner-optin` | `{"enabled": true}` — alleen je eigen toestemming (maintainer) |
121
122### Volledige setup met alleen een token
123
124```sh
125export BLUEGIT_URL=https://git.timfalken.com BLUEGIT_TOKEN=bg_... # scope runners
126bg runner setup mijn-pc # token maken, sudo bluegit-runner register, wachten tot online
127# of los:
128BLUEGIT_RUNNER_REGISTRATION_TOKEN=$(bg runner token) \
129BLUEGIT_RUNNER_URL=$BLUEGIT_URL BLUEGIT_RUNNER_NAME=mijn-pc \
130 sudo -E bluegit-runner register
131bg runner wait mijn-pc && bg runner list
132```
133
134`bluegit-runner register` leest `BLUEGIT_RUNNER_REGISTRATION_TOKEN`,
135`BLUEGIT_RUNNER_URL` en `BLUEGIT_RUNNER_NAME` als de vlaggen ontbreken.
136
137## Problemen
138
139```sh
140journalctl -u bluegit-runner -f
141sudo -u bluegit-runner docker info # moet werken (groep docker)
142```