BlueGit

timfa bluegit

Files

bluegit / docs / CI.md

CI.md

feat: merge-request-pipelines en merge na een geslaagde run
timfa project_87923614_bot_3aff574f6f98414b945a8799374f9092 · pushed by timfa · 3 weeks ago
Failed 24b281c4 History
CI.md 7.1 KiB Download Raw

blue-ci-cd.yml

Het bestand ligt in de root van de commit die de pipeline start. De vorm volgt GitLab CI zo ver dat een bestaand .gitlab-ci.yml meestal hernoemd kan worden naar blue-ci-cd.yml. Jobs mogen los op het hoogste niveau staan. Een ouder bestand met een jobs:-map blijft geldig.

stages: [test, build]
variables:
  CGO_ENABLED: "0"
image: alpine:3.20
jobs:
  test:
    stage: test
    image: golang:1.22
    script:
      - go test ./...
    rules:
      - if: $CI_COMMIT_BRANCH == "master"
      - if: $CI_COMMIT_BRANCH =~ /^release\/.*/
  build:
    stage: build
    needs: [test]
    script:
      - go build -o bluegit ./cmd/bluegit
    artifacts:
      paths: [bluegit]
      expire_in: 14d
    allow_failure: false

Velden

VeldBetekenis
stagesVolgorde. Weggelaten: de stages in de volgorde waarin de jobs ze noemen. Een job zonder stage valt in test.
imageStandaardimage, als tekst of als name:. default.image wint als die gezet is.
defaultimage, before_script, after_script, tags, timeout, cache voor jobs die het zelf niet zetten.
includeAlleen local. Een job met dezelfde naam wordt samengevoegd; het buitenste bestand wint per veld.
variablesTekst, of {value: ...}. Een job overschrijft dezelfde naam.
before_script, script, after_scriptafter_script draait ook als script mislukt.
needsNamen, of {job, optional}. needs: [] start meteen. Weggelaten: wacht op eerdere stages.
rulesDe eerste rule die klopt wint. if, changes, exists en when. Zonder rules gelden only en except.
only, exceptTaknaam, branches, tags, of /regex/.
whenon_success (standaard), on_failure, always, manual. In een rule ook never.
allow_failureEen mislukking houdt de rest niet tegen. De job zelf wordt een waarschuwing.
artifactspaths en expire_in (30s, 30m, 12h, 14d, 2w, never).
cachepaths en een tekstuele key. Lokaal per repository, niet gedeeld met een andere machine.
resource_groupJobs met dezelfde naam in één repository draaien niet tegelijk.
timeoutOverschrijft ci.timeout_seconds voor die job.
tagsBewaard bij de job. De ingebouwde runner draait elke job; er is geen tweede runner om op tags te kiezen.
extendsEén naam of een lijst. Een job waarvan de naam met . begint is een sjabloon en draait niet.

Een if is één vergelijking, zonder && of ||:

$NAAM == "waarde"
$NAAM == $ANDERE
$NAAM == null
$NAAM != "waarde"
$NAAM =~ /reguliere-expressie/
$NAAM !~ /reguliere-expressie/

changes kijkt naar de diff van de push. Is die diff niet te bepalen, dan geldt de voorwaarde. exists eist dat elk pad in de commit staat.

Voorgedefinieerd, in rules en in de container: CI, CI_COMMIT_SHA, CI_COMMIT_SHORT_SHA, CI_COMMIT_BRANCH, CI_COMMIT_TAG, CI_COMMIT_REF, CI_COMMIT_REF_NAME, CI_COMMIT_REF_SLUG, CI_COMMIT_TITLE, CI_DEFAULT_BRANCH, CI_PIPELINE_ID, CI_PIPELINE_SOURCE, CI_PIPELINE_URL, CI_PROJECT_PATH, CI_PROJECT_NAME, CI_PROJECT_NAMESPACE, CI_PROJECT_URL, CI_JOB_ID, CI_JOB_NAME, CI_JOB_STAGE, CI_JOB_URL, CI_JOB_TOKEN, CI_API_URL, CI_CONFIG_PATH, CI_SERVER_NAME. Op een tag is CI_COMMIT_BRANCH leeg. CI_PIPELINE_SOURCE is push, web of merge_request_event.

Een merge-request-pipeline start bij het openen van de merge request en bij elke push naar de bronbranch. CI_PIPELINE_SOURCE is dan merge_request_event. Daarbij horen CI_MERGE_REQUEST_ID, CI_MERGE_REQUEST_IID, CI_MERGE_REQUEST_TITLE, CI_MERGE_REQUEST_SOURCE_BRANCH_NAME, CI_MERGE_REQUEST_SOURCE_BRANCH_SHA, CI_MERGE_REQUEST_TARGET_BRANCH_NAME, CI_MERGE_REQUEST_TARGET_BRANCH_SHA, CI_MERGE_REQUEST_PROJECT_PATH en CI_MERGE_REQUEST_PROJECT_URL. De pipeline draait op de commit van de bronbranch. Jobs zonder rules en zonder only: merge_requests doen daar niet aan mee. only: merge_requests en except: merge_requests werken wel. Zodra zo'n bestand jobs voor de merge request kiest, mag er pas gemerged worden als de nieuwste merge-request-pipeline geslaagd is. Een job met allow_failure mag mislukken, maar moet wel af zijn. Een job die nog loopt, in de wachtrij staat of op manual staat, houdt de merge tegen.

Bewust niet

services, pages, workflow, spec, een include van een ander project of van een URL, parallel/matrix, trigger- en child-pipelines, environment, retry, coverage, id_tokens, inherit en hooks. Die sleutels geven een waarschuwing in de editor en houden de rest van het bestand niet tegen. Er is één runner, in het BlueGit-proces, die Docker op dezelfde host aanroept.

Editor

/-/ci/editor opent blue-ci-cd.yml van een branch. De pagina kleurt YAML en zet fouten en waarschuwingen op het regelnummer. Opslaan maakt één commit op de gekozen branch. Bestaat die branch nog niet, dan wordt hij vanaf de geopende branch gemaakt. Een beschermde branch accepteert alleen een beheerder, dezelfde regel als een gewone push.

Mail bij een mislukte pipeline

Komt een pipeline op failed, dan gaat er één mail naar de gebruiker in actor (wie pushte, of wie de run met de hand startte). Dat loopt via POST /api/email op auth.timfalken.com, met de clientgegevens van BlueGit, niet met het token van de gebruiker. Onderwerp en tekst volgen users.language. De mail noemt de repository, het pipeline-nummer, de branch of tag, de jobs die zonder allow_failure faalden, en links naar de pipeline en het joblog. Zonder client_secret (de dev-modus) gaat er niets weg. Een mailfout laat de pipeline met rust.

Geheimen

Repositorygeheimen komen als omgevingsvariabele mee, zoals CI/CD-variabelen. Bij een groepsrepository eerst de groep, daarna de repository; dezelfde naam laat de repository winnen. Een geheim dat als beschermd is gemarkeerd, komt alleen mee als de branch of tag op een beschermd patroon past. Waarden van acht tekens of meer worden in het joblog vervangen door [MASKED]. CI_JOB_TOKEN ook.

Release vanuit een job

curl -fsS -X POST "$CI_API_URL/repos/$CI_PROJECT_PATH/releases" \
  -H "Authorization: Bearer $CI_JOB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag":"v1.2.3","commit":"'"$CI_COMMIT_SHA"'","name":"1.2.3","assets":[{"job":"build","path":"bluegit","name":"bluegit"}]}'

Het commit moet in de repository bestaan. Het asset moet een artifact zijn van een geslaagde job in dezelfde pipeline. Een beheerder kan met een persoonlijk token een release zonder assets maken. Een tag is A-Za-z0-9._-, tot 80 tekens, en wordt ook een annotated git-tag.

Wanneer een job start

Gate in internal/ci geeft ready, wait, skip of fail. skip volgt op een harde mislukking bij when: on_success, of op succes bij when: on_failure. when: always wacht tot de voorgangers klaar zijn en draait dan toch. Een job met allow_failure telt niet als harde mislukking. De runner verwerkt pipelines elke twee seconden, met ci.concurrency tegelijk (standaard 1).

Ontbreekt Docker, dan faalt de job met een regel in het log. De time-out is ci.timeout_seconds (standaard 1800).

Source
1# blue-ci-cd.yml
2
3Het bestand ligt in de root van de commit die de pipeline start. De vorm volgt GitLab CI zo ver dat een bestaand `.gitlab-ci.yml` meestal hernoemd kan worden naar `blue-ci-cd.yml`. Jobs mogen los op het hoogste niveau staan. Een ouder bestand met een `jobs:`-map blijft geldig.
4
5```yaml
6stages: [test, build]
7variables:
8 CGO_ENABLED: "0"
9image: alpine:3.20
10jobs:
11 test:
12 stage: test
13 image: golang:1.22
14 script:
15 - go test ./...
16 rules:
17 - if: $CI_COMMIT_BRANCH == "master"
18 - if: $CI_COMMIT_BRANCH =~ /^release\/.*/
19 build:
20 stage: build
21 needs: [test]
22 script:
23 - go build -o bluegit ./cmd/bluegit
24 artifacts:
25 paths: [bluegit]
26 expire_in: 14d
27 allow_failure: false
28```
29
30## Velden
31
32| Veld | Betekenis |
33| --- | --- |
34| `stages` | Volgorde. Weggelaten: de stages in de volgorde waarin de jobs ze noemen. Een job zonder stage valt in `test`. |
35| `image` | Standaardimage, als tekst of als `name:`. `default.image` wint als die gezet is. |
36| `default` | `image`, `before_script`, `after_script`, `tags`, `timeout`, `cache` voor jobs die het zelf niet zetten. |
37| `include` | Alleen `local`. Een job met dezelfde naam wordt samengevoegd; het buitenste bestand wint per veld. |
38| `variables` | Tekst, of `{value: ...}`. Een job overschrijft dezelfde naam. |
39| `before_script`, `script`, `after_script` | `after_script` draait ook als `script` mislukt. |
40| `needs` | Namen, of `{job, optional}`. `needs: []` start meteen. Weggelaten: wacht op eerdere stages. |
41| `rules` | De eerste rule die klopt wint. `if`, `changes`, `exists` en `when`. Zonder rules gelden `only` en `except`. |
42| `only`, `except` | Taknaam, `branches`, `tags`, of `/regex/`. |
43| `when` | `on_success` (standaard), `on_failure`, `always`, `manual`. In een rule ook `never`. |
44| `allow_failure` | Een mislukking houdt de rest niet tegen. De job zelf wordt een waarschuwing. |
45| `artifacts` | `paths` en `expire_in` (`30s`, `30m`, `12h`, `14d`, `2w`, `never`). |
46| `cache` | `paths` en een tekstuele `key`. Lokaal per repository, niet gedeeld met een andere machine. |
47| `resource_group` | Jobs met dezelfde naam in één repository draaien niet tegelijk. |
48| `timeout` | Overschrijft `ci.timeout_seconds` voor die job. |
49| `tags` | Bewaard bij de job. De ingebouwde runner draait elke job; er is geen tweede runner om op tags te kiezen. |
50| `extends` | Eén naam of een lijst. Een job waarvan de naam met `.` begint is een sjabloon en draait niet. |
51
52Een `if` is één vergelijking, zonder `&&` of `||`:
53
54```text
55$NAAM == "waarde"
56$NAAM == $ANDERE
57$NAAM == null
58$NAAM != "waarde"
59$NAAM =~ /reguliere-expressie/
60$NAAM !~ /reguliere-expressie/
61```
62
63`changes` kijkt naar de diff van de push. Is die diff niet te bepalen, dan geldt de voorwaarde. `exists` eist dat elk pad in de commit staat.
64
65Voorgedefinieerd, in rules en in de container: `CI`, `CI_COMMIT_SHA`, `CI_COMMIT_SHORT_SHA`, `CI_COMMIT_BRANCH`, `CI_COMMIT_TAG`, `CI_COMMIT_REF`, `CI_COMMIT_REF_NAME`, `CI_COMMIT_REF_SLUG`, `CI_COMMIT_TITLE`, `CI_DEFAULT_BRANCH`, `CI_PIPELINE_ID`, `CI_PIPELINE_SOURCE`, `CI_PIPELINE_URL`, `CI_PROJECT_PATH`, `CI_PROJECT_NAME`, `CI_PROJECT_NAMESPACE`, `CI_PROJECT_URL`, `CI_JOB_ID`, `CI_JOB_NAME`, `CI_JOB_STAGE`, `CI_JOB_URL`, `CI_JOB_TOKEN`, `CI_API_URL`, `CI_CONFIG_PATH`, `CI_SERVER_NAME`. Op een tag is `CI_COMMIT_BRANCH` leeg. `CI_PIPELINE_SOURCE` is `push`, `web` of `merge_request_event`.
66
67Een merge-request-pipeline start bij het openen van de merge request en bij elke push naar de bronbranch. `CI_PIPELINE_SOURCE` is dan `merge_request_event`. Daarbij horen `CI_MERGE_REQUEST_ID`, `CI_MERGE_REQUEST_IID`, `CI_MERGE_REQUEST_TITLE`, `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`, `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA`, `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`, `CI_MERGE_REQUEST_TARGET_BRANCH_SHA`, `CI_MERGE_REQUEST_PROJECT_PATH` en `CI_MERGE_REQUEST_PROJECT_URL`. De pipeline draait op de commit van de bronbranch. Jobs zonder `rules` en zonder `only: merge_requests` doen daar niet aan mee. `only: merge_requests` en `except: merge_requests` werken wel. Zodra zo'n bestand jobs voor de merge request kiest, mag er pas gemerged worden als de nieuwste merge-request-pipeline geslaagd is. Een job met `allow_failure` mag mislukken, maar moet wel af zijn. Een job die nog loopt, in de wachtrij staat of op manual staat, houdt de merge tegen.
68
69## Bewust niet
70
71`services`, `pages`, `workflow`, `spec`, een include van een ander project of van een URL, `parallel`/`matrix`, trigger- en child-pipelines, `environment`, `retry`, `coverage`, `id_tokens`, `inherit` en `hooks`. Die sleutels geven een waarschuwing in de editor en houden de rest van het bestand niet tegen. Er is één runner, in het BlueGit-proces, die Docker op dezelfde host aanroept.
72
73## Editor
74
75`/-/ci/editor` opent `blue-ci-cd.yml` van een branch. De pagina kleurt YAML en zet fouten en waarschuwingen op het regelnummer. Opslaan maakt één commit op de gekozen branch. Bestaat die branch nog niet, dan wordt hij vanaf de geopende branch gemaakt. Een beschermde branch accepteert alleen een beheerder, dezelfde regel als een gewone push.
76
77## Mail bij een mislukte pipeline
78
79Komt een pipeline op `failed`, dan gaat er één mail naar de gebruiker in `actor` (wie pushte, of wie de run met de hand startte). Dat loopt via `POST /api/email` op auth.timfalken.com, met de clientgegevens van BlueGit, niet met het token van de gebruiker. Onderwerp en tekst volgen `users.language`. De mail noemt de repository, het pipeline-nummer, de branch of tag, de jobs die zonder `allow_failure` faalden, en links naar de pipeline en het joblog. Zonder `client_secret` (de dev-modus) gaat er niets weg. Een mailfout laat de pipeline met rust.
80
81## Geheimen
82
83Repositorygeheimen komen als omgevingsvariabele mee, zoals CI/CD-variabelen. Bij een groepsrepository eerst de groep, daarna de repository; dezelfde naam laat de repository winnen. Een geheim dat als beschermd is gemarkeerd, komt alleen mee als de branch of tag op een beschermd patroon past. Waarden van acht tekens of meer worden in het joblog vervangen door `[MASKED]`. `CI_JOB_TOKEN` ook.
84
85## Release vanuit een job
86
87```shell
88curl -fsS -X POST "$CI_API_URL/repos/$CI_PROJECT_PATH/releases" \
89 -H "Authorization: Bearer $CI_JOB_TOKEN" \
90 -H "Content-Type: application/json" \
91 -d '{"tag":"v1.2.3","commit":"'"$CI_COMMIT_SHA"'","name":"1.2.3","assets":[{"job":"build","path":"bluegit","name":"bluegit"}]}'
92```
93
94Het commit moet in de repository bestaan. Het asset moet een artifact zijn van een geslaagde job in dezelfde pipeline. Een beheerder kan met een persoonlijk token een release zonder assets maken. Een tag is `A-Za-z0-9._-`, tot 80 tekens, en wordt ook een annotated git-tag.
95
96## Wanneer een job start
97
98`Gate` in `internal/ci` geeft `ready`, `wait`, `skip` of `fail`. `skip` volgt op een harde mislukking bij `when: on_success`, of op succes bij `when: on_failure`. `when: always` wacht tot de voorgangers klaar zijn en draait dan toch. Een job met `allow_failure` telt niet als harde mislukking. De runner verwerkt pipelines elke twee seconden, met `ci.concurrency` tegelijk (standaard 1).
99
100Ontbreekt Docker, dan faalt de job met een regel in het log. De time-out is `ci.timeout_seconds` (standaard 1800).