From 9b21f770e5379910cb49a30409e52369ab1d1b63 Mon Sep 17 00:00:00 2001 From: Niek Otten Date: Fri, 24 Jul 2026 14:15:19 +0200 Subject: [PATCH] docs(runbooks): document the job-summary pattern + version requirement (refs #136) --- docs/runbooks/gitea-actions-gotchas.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/runbooks/gitea-actions-gotchas.md b/docs/runbooks/gitea-actions-gotchas.md index 0be41d3..8ecdfc0 100644 --- a/docs/runbooks/gitea-actions-gotchas.md +++ b/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.