From f7ed978ce9f9df7bf26679b82e9e4194fe6f7915 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Thu, 23 Apr 2026 13:43:40 +0200 Subject: [PATCH] docs(ci): improve Branch Protection section per PR review The original wording was correct but terse. Reviewer (#874) suggested a clearer 4-bullet structure that adds a 'How the name is derived' bullet explaining the job 'name:' vs job-id fallback rule. This makes the diagnostic process explicit for future contributors who hit the same 'Expected - Waiting for status to be reported' symptom. Also tightens the gotcha bullet: the previous wording said the context must 'match' the check-run name, which left room for ambiguity. The new wording says it must BE the literal check-run name and explicitly explains that 'Merge Gate / gate' is a UI rendering, not a value. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/instructions/cicd.instructions.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/instructions/cicd.instructions.md b/.github/instructions/cicd.instructions.md index 49e39628..7c5980f1 100644 --- a/.github/instructions/cicd.instructions.md +++ b/.github/instructions/cicd.instructions.md @@ -88,9 +88,10 @@ integration suite runs only at merge time via GitHub Merge Queue - **Cross-workflow artifacts**: ci-integration.yml builds the binary inline (no cross-workflow artifact transfer); build-release.yml jobs share artifacts within the same workflow run. ## Branch Protection & Required Checks -- **Single required check**: branch protection (`main-protection` ruleset id 9294522) requires only one status check: `gate` from `merge-gate.yml`. All other PR-time signals are aggregated by that workflow's poll loop. -- **CRITICAL ruleset gotcha**: the `context` field stored in the ruleset must match the **check-run name** (the job key, e.g. `gate`), NOT the GitHub UI's display string (`Merge Gate / gate`). Storing the display string causes permanent "Expected - Waiting for status to be reported" because no check-run with that literal name ever posts. The integration_id (`15368` = github-actions) plus the check-run name is what GitHub matches. -- **Adding a new required check**: add it to `EXPECTED_CHECKS` in `merge-gate.yml`. Do NOT touch the ruleset. +- **Single required check**: branch protection (`main-protection` ruleset id 9294522) requires exactly one status check context: `gate` from `merge-gate.yml`. All other PR-time signals are aggregated by that workflow's poll loop. +- **CRITICAL ruleset gotcha**: the ruleset `context` must be the literal check-run name `gate`. `Merge Gate / gate` is only how GitHub may render the workflow and job together in the UI; it is not the context value to store in the ruleset. If the ruleset stores `Merge Gate / gate`, GitHub waits forever with "Expected - Waiting for status to be reported" because no check-run with that literal name is posted. +- **How the name is derived**: GitHub matches the check by `integration_id` (`15368` = github-actions) plus the emitted check-run name. That emitted name comes from the job `name:` if one is set; otherwise it falls back to the job id. In `merge-gate.yml` the job id is `gate` and `name: gate`, so the emitted check-run name is `gate` -- that is the exact string the ruleset must require. +- **Adding a new aggregated check**: add it to `EXPECTED_CHECKS` in `merge-gate.yml`. Do not change the ruleset unless you intentionally rename the merge gate job's emitted check-run name, in which case the ruleset `context` must be updated to the new exact name. ## Trust Model - **PR push (any contributor, including forks)**: Runs Tier 1 only. No CI secrets exposed. PR code is checked out and tested in an unprivileged context.