BlueGit voor agents en scripts
scripts/bg is een kleine CLI op de BlueGit-API. Hij heeft alleen bash, curl en jq nodig.
export BLUEGIT_URL=https://git.timfalken.com # standaard
export BLUEGIT_TOKEN=... # optioneel, nooit printen
scripts/bg help
Rechten
- Publieke projecten zijn zonder token leesbaar, net als in de UI. Dat geldt voor status, pipelines, jobs, logs, MR's, issues, bestanden en releases.
- Privé projecten, en projecten in een privé groep, geven
404zonder token of als je geen lid bent. Je ziet dus ook niet of zo'n project bestaat. - Schrijven (MR, notitie, issue, branch, release, retry) vraagt altijd een token, met de rol die de UI ook vraagt. Zonder token krijg je
401, met te weinig rechten403. - Een token werkt met de rechten van de eigenaar, beperkt door de scopes van het token (
read_api,api, …).
bg zet fouten op stderr met de HTTP-code en eindigt met exit 1. Een 404 kan dus ook "geen toegang" betekenen.
Pipelines
bg pipeline status timfa/bluegit --branch stage # nieuwste pipeline op een branch
bg pipeline status timfa/bluegit --sha 3e6b2f1 # op commit (prefix van 7+ tekens)
bg pipeline status timfa/bluegit --mr 40 # van MR 40 (incl. pushes naar de bronbranch)
bg pipeline status timfa/bluegit --id 158
bg pipeline wait timfa/bluegit --sha "$(git rev-parse HEAD)" --timeout 1200 --interval 10
bg pipeline logs timfa/bluegit 158 611
bg pipeline retry timfa/bluegit 158 # alleen mislukte jobs (+ wat daarop wachtte)
bg pipeline retry timfa/bluegit 158 --all # nieuwe pipeline
# beide alleen als minstens één job gefaald is (ook runner_system_failure); anders 409, en de UI toont dan geen retry-knop
wait wacht eerst tot er voor de selectie een pipeline is (handig direct na een push) en daarna tot die klaar is. De exitcodes:
| exit | betekenis |
|---|---|
| 0 | success |
| 1 | failed of canceled; de laatste 80 regels van elke mislukte job staan op stderr (BG_LOG_LINES om aan te passen) |
| 2 | timeout |
Jobs met allow_failure die faalden geven een waarschuwing, maar het blijft exit 0.
Typisch voor een cloud-agent na een push:
git push bluegit HEAD:refs/heads/mijn-branch
sha=$(git rev-parse HEAD)
if scripts/bg pipeline wait timfa/bluegit --sha "$sha" --timeout 1800; then
echo groen
else
echo "rood of timeout ($?)"; exit 1
fi
Merge requests
bg mr list timfa/bluegit # open
bg mr list timfa/bluegit --state all --source mijn-branch
bg mr create timfa/bluegit --source mijn-branch --target stage --title "fix: ..." --description "..."
bg mr show timfa/bluegit 40
bg mr comment timfa/bluegit 40 "Ziet er goed uit"
bg mr merge timfa/bluegit 40 # verwijdert de bronbranch; --keep-source om te houden
Issues, branches, releases, bestanden
bg issue list timfa/bluegit [open|closed|all]
bg issue create timfa/bluegit "Titel" "Beschrijving"
bg issue comment timfa/bluegit 7 "Opgelost in !40"
bg issue close timfa/bluegit 7
bg branch create timfa/bluegit mijn-branch --from stage
bg release create timfa/bluegit v1.2.0 --commit <sha> --asset build:bluegit:bluegit-linux-amd64
bg file get timfa/bluegit README.md --ref stage
Een release-asset komt uit een artifact van een job in dezelfde repo (JOB:PAD[:NAAM]). Een los bestand uploaden kan de API nog niet.
Ruwe API
De CLI is dun. Alles staat ook in /api/v1/openapi.json. Handige filters:
GET /api/v1/projects/{owner}/{repo}/pipelines?sha=…|ref=…|mr=…GET /api/v1/projects/{owner}/{repo}/merge_requests?state=open|merged|closed|all&source_branch=…&target_branch=…GET /api/v1/projects/{owner}/{repo}/pipelines/{id}/jobs/{job}/log
Owner en repo zijn twee padsegmenten (timfa/bluegit), niet urlencoded.
Self-update en wachtende pipelines
Staat er een self-update klaar, dan starten nieuwe pipelines niet. Ze hebben dan status waiting_for_update (in de UI "Wacht op update"), en bg pipeline wait blijft gewoon wachten. Lopende pipelines mogen afmaken. Daarna installeert de updater, en na de herstart starten de wachtende pipelines vanzelf.
- Maximale wachttijd:
ci.update_max_wait_minutes(standaard 30). Is die verstreken, dan gaat de poort weer open. - Forceren (installeren zonder te wachten):
- als beheerder:
POST /api/v1/admin/self-update/force - met het update-token:
POST /api/v1/admin/self-updatemet{"force":true}
Runners
Runnerbeheer kan helemaal met een access token met scope runners (zie runner.md):
bg runner list [--group PAD] # id, status, naam, laatst gezien, versie
bg runner token [--group PAD] # registratietoken (eenmalig, 24 uur) op stdout
bg runner setup [NAAM] [--group PAD] # token + sudo bluegit-runner register + wachten tot online
bg runner wait NAAM|ID [--timeout S] # exit 0 online, 2 timeout
bg runner rename ID NAAM | pause ID | resume ID | delete ID | jobs ID
bg runner pref [own_first|builtin_first] # accountvoorkeur
bg runner builtin-first --group PAD [true|false]
bg runner optin --group PAD [on|off] # alleen je eigen toestemming, als maintainer
Het registratietoken is het enige geheim dat bg print, en alleen bij bg runner token; geef het via BLUEGIT_RUNNER_REGISTRATION_TOKEN door in plaats van op de commandoregel. Een job-token (CI_JOB_TOKEN) kan geen runners beheren.
Instellingen, pauze en jobs van een runner (zie runner.md):
- aparte runner: de lokale API op de runnermachine (
http://127.0.0.1:8765/api/...)
met het beheertoken uit sudo bluegit-runner ui-token;
- ingebouwde runner:
/api/v1/admin/runner/{status,settings,jobs,pause,resume}
met het token van een sitebeheerder (scope runners of api).
curl -fsS -H "Authorization: Bearer $BLUEGIT_TOKEN" $BLUEGIT_URL/api/v1/admin/runner/status
curl -fsS -X PUT -H "Authorization: Bearer $BLUEGIT_TOKEN" -H 'Content-Type: application/json' \
-d '{"concurrency":2,"memory_mb":4096}' $BLUEGIT_URL/api/v1/admin/runner/settings
Beheerders (alleen voor sitebeheerders, token met scope api):
GET /api/v1/admin/usersgeeft alle gebruikers metadmin: true|false.PUT /api/v1/admin/users/{username}/adminmet{"admin": true}of{"admin": false}kent de rol toe of neemt hem af.- Jezelf afnemen geeft 403. Als er geen beheerder over zou blijven, krijg je 409. Een onbekende gebruiker geeft 404.
- Elke wijziging komt als regel
admin auditin de serverlog (journal), met actie, door wie en voor wie.
bg admin list
bg admin grant bob
bg admin revoke bob
Source
| 1 | # BlueGit voor agents en scripts |
| 2 | |
| 3 | `scripts/bg` is een kleine CLI op de BlueGit-API. Hij heeft alleen `bash`, `curl` en `jq` nodig. |
| 4 | |
| 5 | ```sh |
| 6 | export BLUEGIT_URL=https://git.timfalken.com # standaard |
| 7 | export BLUEGIT_TOKEN=... # optioneel, nooit printen |
| 8 | scripts/bg help |
| 9 | ``` |
| 10 | |
| 11 | ## Rechten |
| 12 | |
| 13 | - **Publieke projecten** zijn zonder token leesbaar, net als in de UI. Dat geldt voor status, pipelines, jobs, logs, MR's, issues, bestanden en releases. |
| 14 | - **Privé projecten**, en projecten in een privé groep, geven `404` zonder token of als je geen lid bent. Je ziet dus ook niet of zo'n project bestaat. |
| 15 | - **Schrijven** (MR, notitie, issue, branch, release, retry) vraagt altijd een token, met de rol die de UI ook vraagt. Zonder token krijg je `401`, met te weinig rechten `403`. |
| 16 | - **Een token** werkt met de rechten van de eigenaar, beperkt door de scopes van het token (`read_api`, `api`, …). |
| 17 | |
| 18 | `bg` zet fouten op stderr met de HTTP-code en eindigt met exit 1. Een 404 kan dus ook "geen toegang" betekenen. |
| 19 | |
| 20 | ## Pipelines |
| 21 | |
| 22 | ```sh |
| 23 | bg pipeline status timfa/bluegit --branch stage # nieuwste pipeline op een branch |
| 24 | bg pipeline status timfa/bluegit --sha 3e6b2f1 # op commit (prefix van 7+ tekens) |
| 25 | bg pipeline status timfa/bluegit --mr 40 # van MR 40 (incl. pushes naar de bronbranch) |
| 26 | bg pipeline status timfa/bluegit --id 158 |
| 27 | |
| 28 | bg pipeline wait timfa/bluegit --sha "$(git rev-parse HEAD)" --timeout 1200 --interval 10 |
| 29 | bg pipeline logs timfa/bluegit 158 611 |
| 30 | bg pipeline retry timfa/bluegit 158 # alleen mislukte jobs (+ wat daarop wachtte) |
| 31 | bg pipeline retry timfa/bluegit 158 --all # nieuwe pipeline |
| 32 | # beide alleen als minstens één job gefaald is (ook runner_system_failure); anders 409, en de UI toont dan geen retry-knop |
| 33 | ``` |
| 34 | |
| 35 | `wait` wacht eerst tot er voor de selectie een pipeline is (handig direct na een push) en daarna tot die klaar is. De exitcodes: |
| 36 | |
| 37 | | exit | betekenis | |
| 38 | |---|---| |
| 39 | | 0 | success | |
| 40 | | 1 | failed of canceled; de laatste 80 regels van elke mislukte job staan op stderr (`BG_LOG_LINES` om aan te passen) | |
| 41 | | 2 | timeout | |
| 42 | |
| 43 | Jobs met `allow_failure` die faalden geven een waarschuwing, maar het blijft exit 0. |
| 44 | |
| 45 | Typisch voor een cloud-agent na een push: |
| 46 | |
| 47 | ```sh |
| 48 | git push bluegit HEAD:refs/heads/mijn-branch |
| 49 | sha=$(git rev-parse HEAD) |
| 50 | if scripts/bg pipeline wait timfa/bluegit --sha "$sha" --timeout 1800; then |
| 51 | echo groen |
| 52 | else |
| 53 | echo "rood of timeout ($?)"; exit 1 |
| 54 | fi |
| 55 | ``` |
| 56 | |
| 57 | ## Merge requests |
| 58 | |
| 59 | ```sh |
| 60 | bg mr list timfa/bluegit # open |
| 61 | bg mr list timfa/bluegit --state all --source mijn-branch |
| 62 | bg mr create timfa/bluegit --source mijn-branch --target stage --title "fix: ..." --description "..." |
| 63 | bg mr show timfa/bluegit 40 |
| 64 | bg mr comment timfa/bluegit 40 "Ziet er goed uit" |
| 65 | bg mr merge timfa/bluegit 40 # verwijdert de bronbranch; --keep-source om te houden |
| 66 | ``` |
| 67 | |
| 68 | ## Issues, branches, releases, bestanden |
| 69 | |
| 70 | ```sh |
| 71 | bg issue list timfa/bluegit [open|closed|all] |
| 72 | bg issue create timfa/bluegit "Titel" "Beschrijving" |
| 73 | bg issue comment timfa/bluegit 7 "Opgelost in !40" |
| 74 | bg issue close timfa/bluegit 7 |
| 75 | |
| 76 | bg branch create timfa/bluegit mijn-branch --from stage |
| 77 | bg release create timfa/bluegit v1.2.0 --commit <sha> --asset build:bluegit:bluegit-linux-amd64 |
| 78 | bg file get timfa/bluegit README.md --ref stage |
| 79 | ``` |
| 80 | |
| 81 | Een release-asset komt uit een artifact van een job in dezelfde repo (`JOB:PAD[:NAAM]`). Een los bestand uploaden kan de API nog niet. |
| 82 | |
| 83 | ## Ruwe API |
| 84 | |
| 85 | De CLI is dun. Alles staat ook in `/api/v1/openapi.json`. Handige filters: |
| 86 | |
| 87 | - `GET /api/v1/projects/{owner}/{repo}/pipelines?sha=…|ref=…|mr=…` |
| 88 | - `GET /api/v1/projects/{owner}/{repo}/merge_requests?state=open|merged|closed|all&source_branch=…&target_branch=…` |
| 89 | - `GET /api/v1/projects/{owner}/{repo}/pipelines/{id}/jobs/{job}/log` |
| 90 | |
| 91 | Owner en repo zijn twee padsegmenten (`timfa/bluegit`), niet urlencoded. |
| 92 | |
| 93 | ## Self-update en wachtende pipelines |
| 94 | |
| 95 | Staat er een self-update klaar, dan starten nieuwe pipelines niet. Ze hebben dan status `waiting_for_update` (in de UI "Wacht op update"), en `bg pipeline wait` blijft gewoon wachten. Lopende pipelines mogen afmaken. Daarna installeert de updater, en na de herstart starten de wachtende pipelines vanzelf. |
| 96 | |
| 97 | - **Maximale wachttijd:** `ci.update_max_wait_minutes` (standaard 30). Is die verstreken, dan gaat de poort weer open. |
| 98 | - **Forceren** (installeren zonder te wachten): |
| 99 | - als beheerder: `POST /api/v1/admin/self-update/force` |
| 100 | - met het update-token: `POST /api/v1/admin/self-update` met `{"force":true}` |
| 101 | |
| 102 | ## Runners |
| 103 | |
| 104 | Runnerbeheer kan helemaal met een access token met scope `runners` |
| 105 | (zie [runner.md](runner.md#beheer-via-de-api-en-voor-agents)): |
| 106 | |
| 107 | ```sh |
| 108 | bg runner list [--group PAD] # id, status, naam, laatst gezien, versie |
| 109 | bg runner token [--group PAD] # registratietoken (eenmalig, 24 uur) op stdout |
| 110 | bg runner setup [NAAM] [--group PAD] # token + sudo bluegit-runner register + wachten tot online |
| 111 | bg runner wait NAAM|ID [--timeout S] # exit 0 online, 2 timeout |
| 112 | bg runner rename ID NAAM | pause ID | resume ID | delete ID | jobs ID |
| 113 | bg runner pref [own_first|builtin_first] # accountvoorkeur |
| 114 | bg runner builtin-first --group PAD [true|false] |
| 115 | bg runner optin --group PAD [on|off] # alleen je eigen toestemming, als maintainer |
| 116 | ``` |
| 117 | |
| 118 | Het registratietoken is het enige geheim dat `bg` print, en alleen bij |
| 119 | `bg runner token`; geef het via `BLUEGIT_RUNNER_REGISTRATION_TOKEN` door |
| 120 | in plaats van op de commandoregel. Een job-token (`CI_JOB_TOKEN`) kan geen |
| 121 | runners beheren. |
| 122 | |
| 123 | **Instellingen, pauze en jobs van een runner** (zie [runner.md](runner.md#lokale-api)): |
| 124 | |
| 125 | - aparte runner: de lokale API op de runnermachine (`http://127.0.0.1:8765/api/...`) |
| 126 | met het beheertoken uit `sudo bluegit-runner ui-token`; |
| 127 | - ingebouwde runner: `/api/v1/admin/runner/{status,settings,jobs,pause,resume}` |
| 128 | met het token van een sitebeheerder (scope `runners` of `api`). |
| 129 | |
| 130 | ```sh |
| 131 | curl -fsS -H "Authorization: Bearer $BLUEGIT_TOKEN" $BLUEGIT_URL/api/v1/admin/runner/status |
| 132 | curl -fsS -X PUT -H "Authorization: Bearer $BLUEGIT_TOKEN" -H 'Content-Type: application/json' \ |
| 133 | -d '{"concurrency":2,"memory_mb":4096}' $BLUEGIT_URL/api/v1/admin/runner/settings |
| 134 | ``` |
| 135 | |
| 136 | **Beheerders** (alleen voor sitebeheerders, token met scope `api`): |
| 137 | |
| 138 | - `GET /api/v1/admin/users` geeft alle gebruikers met `admin: true|false`. |
| 139 | - `PUT /api/v1/admin/users/{username}/admin` met `{"admin": true}` of `{"admin": false}` kent de rol toe of neemt hem af. |
| 140 | - Jezelf afnemen geeft 403. Als er geen beheerder over zou blijven, krijg je 409. Een onbekende gebruiker geeft 404. |
| 141 | - Elke wijziging komt als regel `admin audit` in de serverlog (journal), met actie, door wie en voor wie. |
| 142 | |
| 143 | ```sh |
| 144 | bg admin list |
| 145 | bg admin grant bob |
| 146 | bg admin revoke bob |
| 147 | ``` |