.gitea/workflows/ci.yaml

@@ -54,7 +54,9 @@ jobs:
       # Publish the Stryker HTML report. `if: always()` uploads it even when the
       # ratchet fails — that is exactly when you want to inspect the survivors.
       # Glob handles Stryker's non-deterministic StrykerOutput/<timestamp>/ dir.
-      - uses: https://github.com/actions/upload-artifact@v4
+      # Pinned to @v3 deliberately: @v4 refuses to run on Gitea (GHES guard) —
+      # see docs/runbooks/gitea-actions-gotchas.md §4.
+      - uses: https://github.com/actions/upload-artifact@v3
         if: always()
         with:
           name: acl-mutation-report

docs/runbooks/ci.md

@@ -58,10 +58,10 @@ open it to see survived vs. killed mutants.
 In CI the `mutation` job publishes that report as the **`acl-mutation-report`** artifact
 (download it from the run's summary page). The upload step uses `if: always()`, so the
 report is available even when the ratchet *fails* — which is exactly when you want to inspect
-the survivors. It is the repo's first use of `actions/upload-artifact` (pinned, `@v4`);
+the survivors. It is the repo's first use of `actions/upload-artifact`, pinned to **`@v3`**:
-Gitea ≥1.24 supports v4 and this instance runs 1.25.x. If a future Gitea/runner combination
+`@v4` refuses to run on Gitea (its `@actions/artifact` v2 library blocks any non-github.com
-can't store artifacts, treat it as a known gap per §15 and record it in
+server as "GHES"), while `@v3` speaks the artifact protocol Gitea implements. See
-[gitea-actions-gotchas.md](gitea-actions-gotchas.md) rather than blocking merges on it.
+[gitea-actions-gotchas.md §4](gitea-actions-gotchas.md) (§15).
 
 ## Running the stack locally without `make` (Windows / Docker Desktop)
 

docs/runbooks/gitea-actions-gotchas.md

@@ -13,6 +13,7 @@ those containers share a filesystem — or a `localhost` — breaks.
 | 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) |
 
 ---
 
@@ -98,3 +99,28 @@ plus app start.
 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.