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.**
 

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