# BlueGit voor agents en scripts `scripts/bg` is een kleine CLI op de BlueGit-API. Hij heeft alleen `bash`, `curl` en `jq` nodig. ```sh 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 `404` zonder 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 rechten `403`. - **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 ```sh 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 ``` `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: ```sh 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 ```sh 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 ```sh 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 --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-update` met `{"force":true}` ## Runners Runnerbeheer kan helemaal met een access token met scope `runners` (zie [runner.md](runner.md#beheer-via-de-api-en-voor-agents)): ```sh 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.