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

```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 <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](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.

**Instellingen, pauze en jobs van een runner** (zie [runner.md](runner.md#lokale-api)):

- 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`).

```sh
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.

```sh
bg admin list
bg admin grant bob
bg admin revoke bob
```

## Globale runners (beheerders)

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

```sh
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.

## Release op een bestaande tag

`POST /api/v1/repos/{owner}/{repo}/releases/{tag}/assets` publiceert een release wanneer de git-tag al bestaat. Alleen een lopend jobtoken van de push-pipeline `refs/tags/{tag}`. Geen `replace`. De tag blijft byte voor byte dezelfde ref. Een bestaande release geeft `409`. Assets komen uit geslaagde jobs van die pipeline. Zie [CI.md](CI.md#release-bij-een-tag-die-al-bestaat).

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

```sh
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.
