diff --git a/runbooks/gitea-operational-quirks.md b/runbooks/gitea-operational-quirks.md index b48fe861..3bc1cd94 100644 --- a/runbooks/gitea-operational-quirks.md +++ b/runbooks/gitea-operational-quirks.md @@ -141,12 +141,51 @@ files. Secrets and variables are repo-level. --- -## `fetch-depth: 0` on `actions/checkout` times out +## Gitea combined status reports `failure` when all contexts are `null` -`actions/checkout` with `fetch-depth: 0` triggers a full repo history fetch -which exceeds the runner's network timeout to the git remote (~15 s). +### Finding -**Workaround**: Use `fetch-depth: 1` (default) and add explicit -`git fetch origin --depth=1` for any additional refs needed. +When ALL individual status contexts for a commit have `state: null` (no runner +has reported yet), Gitea reports the combined commit status as `failure`. This +is a Gitea Actions bug — it conflates "no status reported yet" with "failed". -**Reference**: PR #441 detect-changes fetch step. +### Impact + +- The `main-red-watchdog` workflow opens a `[main-red]` issue for every + scheduled workflow run where the combined state is `failure` — even when + the failure is entirely due to Gitea's combined-status bug. +- This causes spurious `[main-red]` issues that waste SRE time investigating + non-existent failures. +- **This is especially confusing for `schedule:`-only workflows** (canary, + sweep jobs, synth-E2E): Gitea attributes their scheduled runs to `main`'s + HEAD commit, so if a scheduled run fires while all contexts are still + `state: null`, the watchdog opens a `[main-red]` issue on the latest main + commit even though that commit itself is perfectly fine. + +### How to diagnose + +Always check the **individual context `state` fields**, not the combined +`state`/`combined_state`. In the `/repos/{org}/{repo}/commits/{sha}/statuses` +API response, look for `"state": null` on every entry — if all are null, the +combined `failure` is Gitea's bug, not a real CI failure. + +```json +{ + "combined_state": "failure", // ← Gitea bug when all are null + "contexts": [ + { "context": "CI / Lint", "state": null }, // still running + { "context": "CI / Test", "state": null } // still running + ] +} +``` + +### Affected workflows + +All workflows, but especially `schedule:`-only workflows that run on `main`. +The main-red-watchdog (`.gitea/workflows/main-red-watchdog.yml`) is the +primary consumer of combined status and is affected. + +### References + +- Issue #481: first real-world case of this bug (2026-05-11) +- `feedback_no_such_thing_as_flakes`: watchdog directive