BlueGit

timfa bluegit

Files

bluegit / docs / agents.md

agents.md

agents.md 3.7 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.

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.