From 02bdd43fa1f8983d71eeeb6225e51b3f81db3818 Mon Sep 17 00:00:00 2001
From: julien <jgautier.webdev@gmail.com>
Date: Mon, 4 May 2026 11:06:56 +0200
Subject: [PATCH] fix(ci): pin act_runner job image to
 catthehacker/ubuntu:act-22.04 (#4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 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: https://git.unespace.com/julien/apf_portal/pulls/4
---
 docs/decisions/0015-cicd-gitea-actions.md |  2 +-
 infra/ci-runners.compose.yml              | 24 ++++++++++++++++++++---
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/docs/decisions/0015-cicd-gitea-actions.md b/docs/decisions/0015-cicd-gitea-actions.md
index 96460fd..dabb386 100644
--- a/docs/decisions/0015-cicd-gitea-actions.md
+++ b/docs/decisions/0015-cicd-gitea-actions.md
@@ -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.**
 
diff --git a/infra/ci-runners.compose.yml b/infra/ci-runners.compose.yml
index 0c3fe94..7f83ee5 100644
--- a/infra/ci-runners.compose.yml
+++ b/infra/ci-runners.compose.yml
@@ -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