# 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. ```yaml 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 | Veld | Betekenis | | --- | --- | | `stages` | Volgorde. Weggelaten: de stages in de volgorde waarin de jobs ze noemen. Een job zonder stage valt in `test`. | | `image` | Standaardimage, als tekst of als `name:`. `default.image` wint als die gezet is. | | `default` | `image`, `before_script`, `after_script`, `tags`, `timeout`, `cache` voor jobs die het zelf niet zetten. | | `include` | Alleen `local`. Een job met dezelfde naam wordt samengevoegd; het buitenste bestand wint per veld. | | `variables` | Tekst, of `{value: ...}`. Een job overschrijft dezelfde naam. | | `before_script`, `script`, `after_script` | `after_script` draait ook als `script` mislukt. | | `workflow` | `rules` zoals bij een job. Geen passende rule, of `when: never`, maakt geen pipeline. | | `needs` | Namen, of `{job, optional}`. `needs: []` start meteen. Weggelaten: wacht op eerdere stages. Een `needs` op een `parallel`-job wacht op elke instantie. | | `rules` | De eerste rule die klopt wint. `if`, `changes`, `exists` en `when`. Zonder rules gelden `only` en `except`. | | `only`, `except` | Taknaam, `branches`, `tags`, of `/regex/`. | | `when` | `on_success` (standaard), `on_failure`, `always`, `manual`. In een rule ook `never`. | | `allow_failure` | Een mislukking houdt de rest niet tegen. De job zelf wordt een waarschuwing. | | `artifacts` | `paths` en `expire_in` (`30s`, `30m`, `12h`, `14d`, `2w`, `never`). | | `cache` | `paths` en een tekstuele `key`. Lokaal per repository, niet gedeeld met een andere machine. | | `resource_group` | Jobs met dezelfde naam in één repository draaien niet tegelijk. | | `timeout` | Overschrijft `ci.timeout_seconds` voor die job. De runner stopt de container als de tijd om is. | | `retry` | Een getal, of `{max, when}`. `max` is 0 tot 2; hoger wordt afgekapt. `retry: 2` herhaalt elke mislukking behalve een annulering. `when` noemt `script_failure`, `runner_system_failure`, `job_execution_timeout`, `stuck_or_timeout_failure` of `always`. | | `parallel` | Een getal, hoogstens 50. De jobs heten `naam 1/N` en krijgen `CI_NODE_INDEX` en `CI_NODE_TOTAL`. | | `parallel:matrix` | Per lijstitem het cartesisch product, daarna aan elkaar. De job heet `naam: [waarde, waarde]`. De sleutels worden variabelen, in de volgorde uit het bestand. | | `services` | Sidecar-containers op een eigen Docker-netwerk met de job. Een tekst, of `name`, `alias`, `command`, `entrypoint` en `variables`. Zonder alias is dat het imagenaam zonder registry en tag. | | `environment` | Een naam, of `{name, url}`. Zet `CI_ENVIRONMENT_NAME` en `CI_ENVIRONMENT_URL`. Geen deployment en geen `on_stop`. | | `interruptible` | Standaard uit. Een nieuwe pipeline op dezelfde ref annuleert oudere jobs die dit aan hebben en nog in de wachtrij staan of lopen. | | `tags` | Bewaard bij de job. De ingebouwde runner draait elke job; er is geen tweede runner om op tags te kiezen. | | `extends` | Eén naam of een lijst. Een job waarvan de naam met `.` begint is een sjabloon en draait niet. | Een `if` volgt de GitLab-vorm. `&&` bindt sterker dan `||`. Haakjes groeperen. Een lege variabele is `null`. ```text $NAAM == "waarde" && ($ANDERE == "x" || $ANDERE == null) $NAAM != "waarde" $NAAM =~ /reguliere-expressie/ $NAAM =~ /^pad\/met\/slash/ $NAAM =~ /hoofdletters/i $NAAM !~ /reguliere-expressie/ $NAAM =~ $PATROON ``` `=~` en `!~` gebruiken RE2, zonder anker tot je `^` en `$` zelf zet. Een `/` in het patroon schrijf je als `\/`. De vlag `i` staat direct achter de sluithaak. Een patroon in een variabele moet bij het beoordelen een geldige expressie zijn. `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, bij elke push naar de bronbranch, en opnieuw wanneer iemand naar de doelbranch pusht. Die laatste draait nog steeds op de commit van de bronbranch, niet op een samengevoegde boom. `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`, in de rules én in de container. 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, op manual staat of geannuleerd is, houdt de merge tegen. `CI_PIPELINE_ID` is tijdens het beoordelen van rules nog 0. `CI_JOB_ID`, `CI_JOB_NAME`, `CI_JOB_STAGE`, `CI_JOB_URL`, `CI_JOB_TOKEN`, `CI_NODE_INDEX`, `CI_NODE_TOTAL`, `CI_ENVIRONMENT_NAME` en `CI_ENVIRONMENT_URL` bestaan pas in de container. ## Bewust niet `pages`, `spec`, een include van een ander project of van een URL, trigger- en child-pipelines, `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. Zijn naam is `runner.name` in de configuratie, standaard Steve. Die naam staat bij de runner op de jobpagina, op de pipelinedetails en boven het joblog. `tags` kiezen die runner niet. `services` delen één netwerk met de job; er is geen healthcheck verder dan een gestarte container. ## Editor `/-/ci/editor` opent `blue-ci-cd.yml` van een branch. De pagina kleurt YAML en zet fouten en waarschuwingen op het regelnummer. Ontbreekt het bestand, dan opent de editor een uitgecommentarieerd voorbeeld. Opslaan maakt het bestand aan met éé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 voor een directe commit, dezelfde regel als een gewone push. Een ontwikkelaar krijgt dan de keuze om op een nieuwe branch te committen en een merge request te openen. ## 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 ```shell 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). ## Live log De jobpagina vraagt nieuwe regels op zolang de job in de wachtrij staat of loopt, met `?offset=` op het log-adres. De console scrolt mee zolang je onderaan staat; scrol je omhoog, dan blijft de plek staan. ANSI-kleuren worden classes. Geheimen van acht tekens of meer zijn `[MASKED]` op het moment dat de regel wordt weggeschreven, ook in die stream.