# 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. Een preset zoals `bluegit/base` mag. `node:22` blijft een gewoon image. | | `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_COMMIT_TIMESTAMP`, `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`. `CI_COMMIT_TIMESTAMP` is de committer-tijd in ISO 8601. 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 een push naar de bronbranch, en opnieuw wanneer iemand naar de doelbranch pusht en de doelcommit daardoor verandert. Die draait op de commit van de bronbranch, niet op een samengevoegde boom. Dezelfde combinatie van ref, sha, bron, merge request en doelcommit start geen tweede pipeline. Kiezen de rules voor de push en voor de merge request dezelfde jobs, dan blijft één pipeline over en wordt die aan de merge request gekoppeld. Kiezen ze andere jobs, dan blijven beide bestaan en staat op de merge-request-pipeline het label Merge request met het nummer. `CI_PIPELINE_SOURCE` is `merge_request_event` op een pipeline die als merge request is gestart. 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. Steve zet in elke job `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_0=safe.directory` en `GIT_CONFIG_VALUE_0=*`, tenzij de job `safe.directory` zelf al op `*` of `/workspace` zet. De checkout is van de host-gebruiker en de container-user is dat niet. Git 2.35+ weigert die repo anders (`dubious ownership`, exit 128). Scripts in de checkout geven `git -c safe.directory` mee, zodat dit ook werkt op een runner die die variabelen nog niet zet. ## 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. In `Preparing the docker executor` staat altijd `Using docker image …`, en de image-id met digest als het image al lokaal aanwezig is. Een preset schrijft daar ook `Using image preset … based on …` en, na een bouw, `Underlying image … with digest …`. In `Preparing environment` staan de runnernaam, de host, de werkmap `/workspace` en het pipeline- en jobnummer. 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. ## Image-presets Steve heeft geen aparte runners per taal. `image: bluegit/base` en de andere aliassen zijn Dockerfiles in deze repository. Bij het eerste gebruik bouwt Steve ze lokaal en hergebruikt hij het resultaat zolang de Dockerfile hetzelfde blijft. | Preset | Basis | | --- | --- | | `bluegit/base` | Alpine 3.20, met git, curl en bash | | `bluegit/node` | Node.js 22 | | `bluegit/python` | Python 3.12 | | `bluegit/go` | Go 1.22, plus `git-daemon` zodat `git http-backend` aanwezig is | | `bluegit/rust` | Rust 1.81 | | `bluegit/java` | Java 21 (Temurin) | | `bluegit/dotnet` | .NET SDK 8 | Elk image krijgt daar bash, ca-certificates, curl en git bij. `bluegit/go` installeert ook `git-daemon`: daar zit `git-http-backend` in. Zonder die binary valt `git push` over HTTP terug op dumb HTTP en eindigt dat met code 22. `ci.presets` in `config.yml` voegt een alias toe of vervangt een ingebouwde: `image` mapt direct, `dockerfile` wijst naar een bestand, `from` herschrijft de eerste `FROM`. `/-/info` toont deze specificatie en de presets. `GET /api/v1/ci/spec` geeft dezelfde inhoud als JSON. De pagina zet die JSON ook in `