This page is not available in your language yet; it is shown in another language.

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

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-update met {"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/users geeft alle gebruikers met admin: true|false.
PUT /api/v1/admin/users/{username}/admin met {"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 audit in de serverlog (journal), met actie, door wie en voor wie.

bg admin list
bg admin grant bob
bg admin revoke bob

Globale runners (beheerders)

bg admin runner token          # registratietoken + waarschuwing; daarna bluegit-runner register
bg admin runner list
bg admin runner pause 7 ; bg admin runner resume 7 ; bg admin runner rename 7 ci-box ; bg admin runner delete 7

API onder /api/v1/admin/runners (zelfde vorm als /api/v1/user/runners), alleen voor beheerders (403 anders). Globale runners krijgen jobs uit alle repo's, vóór de ingebouwde runner. Zie /help/runners.

Runners en beschermde branches

Jobs op beschermde branches draaien alleen op de ingebouwde runner, globale runners, groepsrunners en account-runners van maintainers/admins van de repo. Opt-in-runners van developers krijgen ze niet; het joblog noemt overgeslagen runners. Zie /help/runners.

Bestanden: raw, download, kopiëren

GET /{owner}/{repo}/-/raw/{pad}?rev=REF geeft alleen de inhoud, met dezelfde toegang als de bestandsweergave (privé: inloggen). Tekst komt als text/plain (ook HTML/SVG, zodat er nooit code van een repo op BlueGit draait), afbeeldingen als afbeelding, binair als application/octet-stream met header X-BlueGit-Binary: 1. &download=1 geeft een bijlage met de bestandsnaam. Max. 50 MB.
In de bestandsweergave staan rechtsboven Download, Raw (nieuw tabblad) en Kopiëren (tekst naar het klembord; binair is uitgeschakeld, fouten komen in een eigen venster). Bij .svg staat een voorbeeld in een wit vlak, geladen als <img> (&as=img), dus scripts in de SVG draaien niet.

Releases en assets verwijderen

bg release delete-asset timfa/app v1.2.0 app-linux.tar.gz   # één bestand; release, tag en broncode blijven
bg release delete timfa/app v1.2.0                          # release met alle bestanden; git-tag blijft
bg release delete timfa/app v1.2.0 --delete-tag             # ook de git-tag weg

API: DELETE /api/v1/projects/{owner}/{repo}/releases/{tag}/assets/{naam} en DELETE /api/v1/projects/{owner}/{repo}/releases/{tag}[?delete_tag=true], beide 204. Alleen eigenaar, maintainer of instance-admin; zonder token 401, niet zichtbaar 404, te weinig rechten 403, onbekende release of asset 404. De bestanden gaan ook van schijf. In de UI staan de knoppen op de Releases-pagina, met een bevestiging.

Zichtbaarheid van releases

Releases hebben een eigen zichtbaarheid naast die van de repo: inherit (zelfde als de repo, standaard), private of public. Instellen kan via Instellingen van de repo, of via:

bg release visibility timfa/app            # tonen
bg release visibility timfa/app public     # zetten (alleen maintainers)
curl -fsS -X PUT -H "Authorization: Bearer $BLUEGIT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"release_visibility":"public"}' $BLUEGIT_URL/api/v1/projects/timfa/app

PUT /api/v1/projects/{owner}/{repo} laat velden die ontbreken ongewijzigd. Een ongeldige waarde geeft 400, een niet-maintainer krijgt 403. GET geeft het veld release_visibility terug.

repo	releases	niet-leden zien
privé	`inherit` / `private`	niets (404/403)
privé	`public`	naam, korte beschrijving en alleen de Releases-pagina: notities en assets. Het project linkt door naar `/-/releases`.
publiek	`inherit` / `public`	alles
publiek	`private`	de code wel, maar geen Releases-pagina, geen release-assets, geen release-API, geen Releases-tab en geen release-markering bij tags

Voor niet-leden blijven altijd privé: code, commits, branches, tags, issues, MR's, pipelines, joblogs, artefacten, instellingen, bron-archieven (zip/tar.gz van tag, branch of commit), git clone over HTTP en SSH, en raw/blob. Leden houden hun rechten, ook via de groep. Dat geldt ook voor tokens en SSH-sleutels, met hun scopes.

Openbaar werken zonder login:

/{owner}/{repo}/-/releases
/{owner}/{repo}/-/releases/{tag}/assets/{naam} (bijv. voor een AUR-PKGBUILD)
GET /api/v1/projects/{owner}/{repo}/releases
.../releases/{tag}/assets/{naam}

Voor niet-leden van een privé repo bevat de release-API geen commit. Releases bevatten alleen assets uit jobs, nooit automatische bron-archieven.