BlueGit

timfa bluegit

Files

bluegit / docs / agents.md

agents.md

agents.md 4.3 KiB Download Raw

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

wait wacht eerst tot er voor de selectie een pipeline is (handig direct na een push) en daarna tot die klaar is. De exitcodes:

exitbetekenis
0success
1failed of canceled; de laatste 80 regels van elke mislukte job staan op stderr (BG_LOG_LINES om aan te passen)
2timeout

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}
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
6export BLUEGIT_URL=https://git.timfalken.com # standaard
7export BLUEGIT_TOKEN=... # optioneel, nooit printen
8scripts/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
23bg pipeline status timfa/bluegit --branch stage # nieuwste pipeline op een branch
24bg pipeline status timfa/bluegit --sha 3e6b2f1 # op commit (prefix van 7+ tekens)
25bg pipeline status timfa/bluegit --mr 40 # van MR 40 (incl. pushes naar de bronbranch)
26bg pipeline status timfa/bluegit --id 158
27
28bg pipeline wait timfa/bluegit --sha "$(git rev-parse HEAD)" --timeout 1200 --interval 10
29bg pipeline logs timfa/bluegit 158 611
30bg pipeline retry timfa/bluegit 158 # alleen mislukte jobs (+ wat daarop wachtte)
31bg pipeline retry timfa/bluegit 158 --all # nieuwe pipeline
32```
33
34`wait` wacht eerst tot er voor de selectie een pipeline is (handig direct na een push) en daarna tot die klaar is. De exitcodes:
35
36| exit | betekenis |
37|---|---|
38| 0 | success |
39| 1 | failed of canceled; de laatste 80 regels van elke mislukte job staan op stderr (`BG_LOG_LINES` om aan te passen) |
40| 2 | timeout |
41
42Jobs met `allow_failure` die faalden geven een waarschuwing, maar het blijft exit 0.
43
44Typisch voor een cloud-agent na een push:
45
46```sh
47git push bluegit HEAD:refs/heads/mijn-branch
48sha=$(git rev-parse HEAD)
49if scripts/bg pipeline wait timfa/bluegit --sha "$sha" --timeout 1800; then
50 echo groen
51else
52 echo "rood of timeout ($?)"; exit 1
53fi
54```
55
56## Merge requests
57
58```sh
59bg mr list timfa/bluegit # open
60bg mr list timfa/bluegit --state all --source mijn-branch
61bg mr create timfa/bluegit --source mijn-branch --target stage --title "fix: ..." --description "..."
62bg mr show timfa/bluegit 40
63bg mr comment timfa/bluegit 40 "Ziet er goed uit"
64bg mr merge timfa/bluegit 40 # verwijdert de bronbranch; --keep-source om te houden
65```
66
67## Issues, branches, releases, bestanden
68
69```sh
70bg issue list timfa/bluegit [open|closed|all]
71bg issue create timfa/bluegit "Titel" "Beschrijving"
72bg issue comment timfa/bluegit 7 "Opgelost in !40"
73bg issue close timfa/bluegit 7
74
75bg branch create timfa/bluegit mijn-branch --from stage
76bg release create timfa/bluegit v1.2.0 --commit <sha> --asset build:bluegit:bluegit-linux-amd64
77bg file get timfa/bluegit README.md --ref stage
78```
79
80Een release-asset komt uit een artifact van een job in dezelfde repo (`JOB:PAD[:NAAM]`). Een los bestand uploaden kan de API nog niet.
81
82## Ruwe API
83
84De CLI is dun. Alles staat ook in `/api/v1/openapi.json`. Handige filters:
85
86- `GET /api/v1/projects/{owner}/{repo}/pipelines?sha=…|ref=…|mr=…`
87- `GET /api/v1/projects/{owner}/{repo}/merge_requests?state=open|merged|closed|all&source_branch=…&target_branch=…`
88- `GET /api/v1/projects/{owner}/{repo}/pipelines/{id}/jobs/{job}/log`
89
90Owner en repo zijn twee padsegmenten (`timfa/bluegit`), niet urlencoded.
91
92## Self-update en wachtende pipelines
93
94Staat 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.
95
96- **Maximale wachttijd:** `ci.update_max_wait_minutes` (standaard 30). Is die verstreken, dan gaat de poort weer open.
97- **Forceren** (installeren zonder te wachten):
98 - als beheerder: `POST /api/v1/admin/self-update/force`
99 - met het update-token: `POST /api/v1/admin/self-update` met `{"force":true}`