register-referentie/docs/runbooks/gitea-actions-gotchas.md

Gitea Actions gotchas

How our CI (Gitea Actions on the hosted ubuntu-latest runner) differs from a local run, and the workarounds in this repo. Referenced by CLAUDE.md §8.7/§15.

One root cause sits under most of this: the runner executes the job inside a container, so when a step runs docker compose up, Compose starts the stack as sibling containers on the host's daemon. Anything that assumes the job and those containers share a filesystem — or a localhost — breaks.

Gotcha	Fix	Lives in
Bind-mounted config arrives empty	docker cp config into external volumes	infra/seed-config.sh
docker compose up --wait is unsupported / flaky	poll health with docker inspect	infra/wait-healthy.sh
pg_isready passes before PostGIS is ready	add a PostGIS_Version() probe	the db healthchecks
upload-artifact@v4 fails ("not supported on GHES")	pin @v3	.gitea/workflows/ci.yaml (mutation job)

---

1. Bind mounts don't reach the containers

Symptom — green locally, but compose-smoke fails with:

oz-init-1 | CommandError: Yaml file `/app/setup_configuration/data.yaml` does not exist.

Migrations run fine; only the step that reads a mounted file fails. The same trap hits nrc-init, flowable-init, and keycloak.

Why — a relative bind mount like ./openzaak/setup_configuration:/app/... is resolved by Compose to a path inside the job container (/workspace/.../setup_configuration). The daemon then looks for that path on its own host, doesn't find it, and mounts an empty directory. (It works on a runner that executes jobs on the host — which is why moving to ubuntu-latest exposed it.)

Fix — use the upstream images verbatim (no build) and stream config into external named volumes with docker cp, which copies over the Docker API and so works wherever the daemon runs. infra/seed-config.sh creates each volume, mounts it in a throwaway helper, and copies the files in:

Asset	Volume	Mounted at
OpenZaak data.yaml	rr-oz-config	oz-init:/app/setup_configuration
Keycloak realms	rr-kc-realms	keycloak:/opt/keycloak/data/import
registratie.bpmn	rr-fl-bpmn	flowable-init:/work

The volumes are external: true with fixed names, so they resolve identically under docker compose and podman-compose. make seeds before every up; make down removes them. (Open Notificaties needs nothing — nrc-init migrates only.)

Consequence — bare docker compose up can't self-seed external volumes:

• CI / Linux / macOS: make up or make smoke (seed, then start).
• No-make / Windows: infra/docker-compose.local.yml — a twin stack that bind-mounts the config instead. Bind mounts are fine locally because a local daemon can see your working directory, so docker compose -f infra/docker-compose.local.yml up -d just works.

Why not the obvious alternatives

• Bake config into an image (incl. an inline Dockerfile) — docker compose up would then work unaided, but it's a build; we wanted the upstream images as-is.
• Compose configs: with inline content — Compose writes a client-side temp file and bind-mounts it, hitting the exact same problem.
• A host-executing runner — bind mounts would work with zero seeding, but it reintroduces a self-hosted runner and undoes the move to ubuntu-latest.

---

2. Readiness: poll health, don't use --wait

docker compose up --wait looks ideal but fails us three ways:

• podman-compose doesn't implement it (unrecognized arguments: --wait) — so it would break local dev.
• A project-wide --wait treats a one-shot exiting 0 as a failure unless something depends_on it with service_completed_successfully. flowable-init deploys the BPMN and exits with no dependant, so --wait fails the moment it does — last line container infra-flowable-init-1 exited (0).
• The containerized runner can't reach published host ports, so an external curl localhost:8080/health can't work either.

Fix — infra/wait-healthy.sh polls each durable service (openzaak nrc-web acl bff, listed as WAIT_SVCS in the Makefile) with docker ps + docker inspect '{{.State.Health.Status}}' until it reports healthy. It uses only primitives both runtimes support, reads the in-container healthcheck (no host port needed), and ignores the one-shots (they only need to have run). WAIT_TIMEOUT defaults to 420 s — enough for the cold OpenZaak migrate (~90 s) plus app start.

---

3. pg_isready passes before PostGIS is ready

pg_isready succeeds as soon as the TCP port is open — before the postgis/postgis image has finished running CREATE EXTENSION postgis. An init container that starts migrating in that window can fail on a missing PostGIS. So the db healthchecks add a SELECT PostGIS_Version() probe, making dependents wait for the extension, not just the port.

---

4. actions/upload-artifact@v4 refuses to run on Gitea

Symptom — the mutation job's make mutation step passes (95% score), but the upload step right after it fails the job:

::error::@actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+
are not currently supported on GHES.
❌  Failure - Main https://github.com/actions/upload-artifact@v4

Why — upload-artifact@v4 bundles @actions/artifact v2, which inspects the server URL and hard-aborts on anything that isn't github.com, treating Gitea as an unsupported GitHub Enterprise Server. The check fires regardless of whether the Gitea server can actually store artifacts (1.24+ can). It is the action, not the server, that refuses.

Fix — pin actions/upload-artifact@v3 (and download-artifact@v3 if ever needed). v3 uses the older artifact protocol that Gitea implements, and has no GHES guard. Inputs are the same (name, path, if-no-files-found), so it is a drop-in swap. Do not bump to @v4 until act_runner advertises github.com-compatible artifact support.