fix(ci): pin upload-artifact to @v3 — @v4 refuses to run on Gitea (refs #47)

The artifact step failed the mutation job: upload-artifact@v4 bundles
@actions/artifact v2, which hard-aborts on any non-github.com server ("not
supported on GHES"), even though Gitea 1.25 stores artifacts fine. @v3 uses the
older protocol Gitea speaks and has no GHES guard — a drop-in swap (same inputs).
Document it as gotcha §4 and correct the CI runbook note.

Refs #47.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitea/workflows/ci.yaml

@@ -51,6 +51,17 @@ jobs:
         with:
           dotnet-version: '10.0.x'
       - run: make mutation
+      # 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.
+      # 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
+          path: services/acl/StrykerOutput/**/reports/mutation-report.html
+          if-no-files-found: warn
 
   compose-smoke:
     runs-on: ubuntu-latest

docs/runbooks/ci.md

@@ -16,7 +16,7 @@ and CI cannot drift:
 | `lint` | `make lint` → `dotnet format … --verify-no-changes` | .NET 10 SDK |
 | `build` | `make build` → `dotnet build … -c Release` | .NET 10 SDK |
 | `unit` | `make unit` → `dotnet test … -c Release` | .NET 10 SDK |
-| `mutation` | `make mutation` → `dotnet tool restore` → `dotnet stryker` (ACL) | .NET 10 SDK |
+| `mutation` | `make mutation` → `dotnet tool restore` → `dotnet stryker` (ACL); uploads the HTML report as an artifact | .NET 10 SDK |
 | `compose-smoke` | `make smoke` → seed config volumes → `up -d` (full stack) → `up --wait` durable services → `down` | container engine + compose v2 |
 
 All `uses:` references are absolute, tag-pinned URLs (`https://github.com/actions/checkout@v4`,
@@ -55,6 +55,14 @@ they gain logic.
 The HTML report is written to `services/acl/StrykerOutput/<timestamp>/reports/` (git-ignored);
 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 to **`@v3`**:
+`@v4` refuses to run on Gitea (its `@actions/artifact` v2 library blocks any non-github.com
+server as "GHES"), while `@v3` speaks the artifact protocol Gitea implements. See
+[gitea-actions-gotchas.md §4](gitea-actions-gotchas.md) (§15).
+
 ## Running the stack locally without `make` (Windows / Docker Desktop)
 
 `make` and the bash helpers assume a Unix shell. To bring the whole stack up on a

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.