From f5f0cd63692ede0389b457c44ec88abef2c805da Mon Sep 17 00:00:00 2001
From: Julien Gautier <julien.gautier@apf.asso.fr>
Date: Mon, 4 May 2026 10:53:23 +0200
Subject: [PATCH] fix(ci): pin act_runner job image to
 catthehacker/ubuntu:act-22.04
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Without an image suffix on the runner labels, act_runner uses a
minimal default container image that has no Node. Every JavaScript
action (actions/checkout, actions/setup-node, nrwl/nx-set-shas, etc.)
crashes during the action's launch step with `Cannot find: node in
PATH`, blocking every CI gate before any project code runs.

The fix is in the runner registration labels: act_runner accepts the
format `<label>:docker://<image>`, which makes act spawn jobs in the
specified container. catthehacker/ubuntu:act-22.04 is the de facto
standard image for act-compatible runners; it bundles Node, Python,
git, common build tools, and the Docker CLI, matching what GitHub
Actions / Gitea Actions workflows generally assume.

infra/ci-runners.compose.yml: GITEA_RUNNER_LABELS updated for the
three runners, with an inline comment explaining the format trap.

docs/decisions/0015-cicd-gitea-actions.md (§Runners): amend the
runner-image baseline. Previous wording said "a Debian image"
without specifying which; now states catthehacker/ubuntu:act-22.04
explicitly and explains the docker:// suffix requirement. Status
remains 'accepted' - the runner-image choice is implementation detail
under the existing decision.

Already-running runners need their labels updated in the Gitea UI
(Site Administration -> Actions -> Runners -> edit each runner) to
the new format. Compose change applies on next re-registration.
Documented as the operational follow-up.
---
 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