docs/runbooks/gitea-actions-gotchas.md

@@ -221,3 +221,27 @@ fails", prefer serialising with a `concurrency` group over `needs` + `always()`.
 **Also** — a run already stuck this way will **not** clear itself; force-cancel it
 from the Actions UI (plain cancel can also stall on this version, #35782). Push the
 workflow fix to produce a fresh run.
+
+---
+
+## 8. Job summaries (`$GITHUB_STEP_SUMMARY`) need Gitea ≥1.27 + runner ≥2.0
+
+Markdown a step appends to the `$GITHUB_STEP_SUMMARY` file renders on the run page
+(no artifact download). We use it for per-run reports (#136): mutation scores
+(Stryker `markdown` reporter), per-service unit results (`infra/trx-summary.py` over
+TRX), per-frontend results (`infra/vitest-summary.py` over each app's vitest JSON),
+the verify-stack check table, and per-spec e2e results (`infra/playwright-summary.py`).
+
+**Requirements / conventions:**
+
+- Requires **Gitea ≥ 1.27** (stores/renders summaries) and **act_runner ≥ 2.0.0**
+  (uploads them). Older pairings silently skip the upload.
+- **Guard every write:** `[ -n "${GITHUB_STEP_SUMMARY:-}" ] || exit 0` — on a runner
+  without support the var is unset and `>> "$GITHUB_STEP_SUMMARY"` would be an
+  ambiguous-redirect error. The guard makes the step a no-op locally / on old runners.
+- Use `if: always()` (step-level) on summary steps so they render even when the thing
+  they report on failed. Step-level `always()` is fine on 2.0.0 — unlike the *job*-level
+  status-function `if` of §7.
+- Getting a report out of the e2e container: Playwright writes `playwright-report.json`
+  inside the container; `infra/run-e2e-check.sh` `docker cp`s it back to the host
+  (capturing the test exit code first) so the summary step can read it.