fix(ci): pin act_runner job image to catthehacker/ubuntu:act-22.04 (#4)
CI / commits (push) Has been skipped
CI / check (push) Failing after 3s
CI / scan (push) Failing after 9s
CI / a11y (push) Failing after 4s
CI / perf (push) Failing after 4s

## Summary

- Pin `act_runner`'s job container image to `catthehacker/ubuntu:act-22.04` via the `<label>:docker://<image>` format on the runner registration labels.
- Update `infra/ci-runners.compose.yml`'s `GITEA_RUNNER_LABELS` for all three runner services, with an inline comment explaining the format requirement.
- Amend ADR-0015 §"Runners" to specify the chosen image and explain the docker-suffix syntax trap.

## Motivation

The first real PR test of the CI pipeline failed at the very first step:

```
Run actions/checkout@v4
0s
Cannot find: node in PATH
 Failure - Main actions/checkout@v4
```

Root cause: `act_runner` registers labels (`self-hosted`, `on-prem`) without a `docker://` image suffix. Without that suffix, act spawns jobs in a minimal default container that has no Node. Every JavaScript action (`actions/checkout`, `actions/setup-node`, `nrwl/nx-set-shas`, the Trivy/gitleaks actions) crashes during the action's launch step. None of the five CI gates can run.

`catthehacker/ubuntu:act-22.04` is the de facto image used by `act` upstream and the standard recommendation for self-hosted Gitea Actions runners. It bundles Node, Python, git, common build tools, and the Docker CLI — exactly the assumed environment for GitHub Actions-compatible workflows.

## Implementation notes

- The fix lives in `GITEA_RUNNER_LABELS` because that's what `act_runner` reads at registration time. The label-to-image mapping is then persisted in the runner's `data/runner-N/.runner` credential.
- For runners **already registered** (i.e. the three currently-running `apf-portal-runner-N`), the persisted credential ignores the new env var. Their labels must be updated through Gitea's UI (Site Administration → Actions → Runners → each runner → edit `Labels`). This is documented in the commit message and is an operational follow-up to merging this PR.
- The compose-file change applies the next time a runner is re-registered (e.g. when `data/runner-N/` is wiped or a new fourth runner is added).
- ADR-0015 amendment is in-place, status remains `accepted`. The runner-image choice is an implementation detail under the existing decision; no new ADR.

## Verification

- [ ] `pnpm ci:check` — n/a, this PR only changes infra and ADR docs, no code paths.
- [ ] **Manual:** after merge + Gitea label updates, the next PR's `actions/checkout@v4` step runs without `Cannot find: node in PATH`.

## Related

- [ADR-0015 — CI/CD pipeline](docs/decisions/0015-cicd-gitea-actions.md). Amended in §"Runners".
- [`infra/README.md`](infra/README.md) — operational doc for the runners; mentions the registration workflow but predates this format requirement. A subsequent docs touch could mirror the new label format there too; deferred to keep this PR scoped to the actual fix.

---------

Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: #4
This commit was merged in pull request #4.
This commit is contained in:
2026-05-04 11:06:56 +02:00
parent a0f6e594ba
commit 02bdd43fa1
2 changed files with 22 additions and 4 deletions
+1 -1
View File
@@ -141,7 +141,7 @@ The level-2 implementation wires both via the CI vendor's cache action; the leve
**Engine.** Gitea Actions, available since Gitea 1.19. The workflow YAML is GitHub Actions-syntax-compatible, which means most third-party actions (`actions/checkout`, `actions/setup-node`, `pnpm/action-setup`, etc.) work unchanged. This compatibility is also a partial migration hedge: the same workflows can be ported to GitHub Actions with near-zero changes if the org pivots to GitHub instead of GitLab.
**Runners.** Three self-hosted `act_runner` instances on internal infrastructure. The first runner is deployed to validate the pipeline; the second and third are added before the project hits any non-trivial PR volume. Runners are labelled `self-hosted`, `on-prem`, plus capacity labels (`size:default`) for future job differentiation. Runner image baseline: a Debian image (aligned with the WSL development environment) pinned by SHA and rebuilt on a cadence by a security-scheduled job.
**Runners.** Three self-hosted `act_runner` instances on internal infrastructure. The first runner is deployed to validate the pipeline; the second and third are added before the project hits any non-trivial PR volume. Runners are labelled `self-hosted` and `on-prem`, plus capacity labels (`size:default`) for future job differentiation. **Job container image** is `catthehacker/ubuntu:act-22.04` — Ubuntu LTS, the de facto standard image for `act`-compatible runners; bundles Node, Python, git, common build tools, and the Docker CLI, so JavaScript actions (`actions/checkout`, `actions/setup-node`, etc.) work without per-job container declarations. Labels are registered in the `<label>:docker://<image>` format; without the `docker://` suffix, `act_runner` falls back to a minimal default image and JavaScript actions fail with `Cannot find: node in PATH`. The image is pinned by tag; the `security-scheduled.yml` workflow re-pulls it weekly to pick up patches.
**Workflow file structure.**
+21 -3
View File
@@ -18,7 +18,13 @@ services:
GITEA_INSTANCE_URL: ${GITEA_INSTANCE_URL:?GITEA_INSTANCE_URL must be set in infra/.env}
GITEA_RUNNER_REGISTRATION_TOKEN: ${GITEA_RUNNER_REGISTRATION_TOKEN:-}
GITEA_RUNNER_NAME: apf-portal-runner-1
GITEA_RUNNER_LABELS: self-hosted,on-prem
# Labels are formatted as <label>:docker://<image>. Without the
# docker:// suffix, act_runner uses a minimal default image with no
# Node, breaking any JavaScript action (actions/checkout etc.).
# catthehacker/ubuntu:act-22.04 is the de facto standard for
# act-compatible runners — bundles Node, Python, git, common build
# tools, and the Docker CLI.
GITEA_RUNNER_LABELS: self-hosted:docker://catthehacker/ubuntu:act-22.04,on-prem:docker://catthehacker/ubuntu:act-22.04
volumes:
# Docker socket — see security note in infra/README.md.
- /var/run/docker.sock:/var/run/docker.sock
@@ -35,7 +41,13 @@ services:
GITEA_INSTANCE_URL: ${GITEA_INSTANCE_URL:?GITEA_INSTANCE_URL must be set in infra/.env}
GITEA_RUNNER_REGISTRATION_TOKEN: ${GITEA_RUNNER_REGISTRATION_TOKEN:-}
GITEA_RUNNER_NAME: apf-portal-runner-2
GITEA_RUNNER_LABELS: self-hosted,on-prem
# Labels are formatted as <label>:docker://<image>. Without the
# docker:// suffix, act_runner uses a minimal default image with no
# Node, breaking any JavaScript action (actions/checkout etc.).
# catthehacker/ubuntu:act-22.04 is the de facto standard for
# act-compatible runners — bundles Node, Python, git, common build
# tools, and the Docker CLI.
GITEA_RUNNER_LABELS: self-hosted:docker://catthehacker/ubuntu:act-22.04,on-prem:docker://catthehacker/ubuntu:act-22.04
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./data/runner-2:/data
@@ -50,7 +62,13 @@ services:
GITEA_INSTANCE_URL: ${GITEA_INSTANCE_URL:?GITEA_INSTANCE_URL must be set in infra/.env}
GITEA_RUNNER_REGISTRATION_TOKEN: ${GITEA_RUNNER_REGISTRATION_TOKEN:-}
GITEA_RUNNER_NAME: apf-portal-runner-3
GITEA_RUNNER_LABELS: self-hosted,on-prem
# Labels are formatted as <label>:docker://<image>. Without the
# docker:// suffix, act_runner uses a minimal default image with no
# Node, breaking any JavaScript action (actions/checkout etc.).
# catthehacker/ubuntu:act-22.04 is the de facto standard for
# act-compatible runners — bundles Node, Python, git, common build
# tools, and the Docker CLI.
GITEA_RUNNER_LABELS: self-hosted:docker://catthehacker/ubuntu:act-22.04,on-prem:docker://catthehacker/ubuntu:act-22.04
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./data/runner-3:/data