The instance moved 1.25.4 -> 1.27.1 during #743, which left a set of deliberately version-pinned CI claims dated rather than wrong. The population was re-derived from `git ls-files` instead of from the issue's own 9-key list, which found ~21 claim sites across workflows, scripts, tests, docs and records. Re-confirmed unchanged on 1.27.1: * an `if:`-skipped job still reports commit-status `skipped`, a distinct state * `compare/{base}...{head}` still serves no `files` * no agent-side cancel route (POST 404, and live swagger has no cancel path at all) * `review-verdict.yml`'s `branches: [main]` still suppresses the run off a non-main base Re-derived from a constructed corpus rather than a sample, because two arbitrary PRs showed only two of the values: the PR file-status vocabulary is changed/added/renamed/ deleted over 200 PRs. All four were already in the closed allow-list, so that set is now evidenced rather than partly presumed. Newly measured, replacing source-attestation. All three arms ran on throwaway scratch-base protection rules, so `main`'s rule was never touched (its updated_at is unchanged at 2026-08-05): * `block_admin_merge_override: false` lets an admin force_merge past an ABSENT required context (HTTP 200); flipping only that field to `true` refuses the identical call (HTTP 405) - the negative control that makes it attributable * an absent required context BLOCKS, so the merge gate does not fail open when review-verdict.yml never runs * `enable_bypass_allowlist` is NOT a better-targeted substitute: enabled with an empty username list, the admin force_merge still succeeded * trap: the PR API reports `mergeable: true` while that same merge is refused, because the field reflects conflict-freedom and ignores branch protection Left explicitly dated rather than silently refreshed, each with its reason: push-supersession auto-cancel is no longer observable on this repo (no workflow triggers on a non-main push, and main refuses direct pushes), and the scope-enum / reqRepoWriter / write:package-403 items need a scoped PAT rather than a read-only probe. review-verdict.yml carries three more 1.25.4-dated comments and is deliberately untouched here: #763 is in-progress on that file and its paging work overlaps them. Refs: #747 Decisions-Edit: yes Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.7 KiB
key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
| key | title | status | since | supersedes | superseded-by | rule | signals | mechanics |
|---|---|---|---|---|---|---|---|---|
| ci.docs-only-skip-steps | 2026-07-17 — Docs-only CI skip gates STEPS in always-running required jobs, never `if:`-skips them (#416) | active | 2026-07-17 | none | none | A docs-only change must still run every required job (`test`, `migrations`) so their commit-status contexts always report; each heavy job runs `scripts/ci-detect-docs-only.sh` first and gates its real STEPS on `if: steps.detect.outputs.docs_only != 'true'`, never `if:`-skips the whole job (an `if:`-skipped job reports `skipped`, not `success`, which branch protection may never unblock on). Detection biases toward running more on any doubt. | docs-only CI skip, required-context branch protection, step-level gating vs job-level `if:` · paths: `.gitea/workflows/docker-build.yml`, `scripts/ci-detect-docs-only.sh` · issues: #416, #418, #420, #398 | `docs/ci-cd.md` → "Docs-only skip" |
A change touching only docs/** or *.md ran the entire docker-build.yml matrix (test,
migrations incl. its mysql:8.4 service, functional-e2e, format, api-docs) — ~9 min of warm
CI to validate Markdown. docker-build.yml had no path filtering.
Why not paths-ignore / an if:-skipped job — the trap. main's branch protection requires
two contexts by name (Build & test (.NET), EF migration integrity (SQLite + MySql)). If a
docs-only PR produced no run for them, those contexts never report and the PR can never merge
— the naive fix bricks docs PRs instead of speeding them. A probe (throwaway PR #418) confirmed that
on Gitea 1.25.4 an if:-skipped job reports commit-status state skipped (a distinct state,
not success); how branch protection treats a skipped required context is not something we rely
on. Re-confirmed unchanged on 1.27.1, 2026-08-28 (#747), without a new probe PR — Build & push image (amd64) is if:-skipped on every PR, and reports skipped on the heads of PR #829
(e5a01dc84100) and PR #828 (02bb0393) alongside success and pending on the rest. The distinct
state survived the upgrade, so the reason this decision gates STEPS rather than jobs still holds.
The decision. Each heavy job (test, migrations, functional-e2e, build) runs
scripts/ci-detect-docs-only.sh as its first post-checkout step (id: detect) and gates every real
step on if: steps.detect.outputs.docs_only != 'true'. The job always runs and reports
success in seconds on docs-only — so the two required contexts report unconditionally (safe by
construction). Non-required jobs may skip freely (production proves a skipped non-required context
doesn't block merge — build is skipped on every PR), so build skips its image steps on a
docs-only push to main (docs aren't in the image); tag builds force docs_only=false so a
release is never skipped. api-docs/format already self-short-circuit; docs-reminder/
decisions-guard/ci-image-pin keep running.
Detection biases toward running MORE. docs_only=true only when every changed path is docs;
any code path, a tag build, a non-merge push, or an undeterminable diff → false (run everything). A
false true would skip real tests on a code change (a correctness bug); a false false merely wastes
CI. Trade-off accepted: migrations' mysql service still starts on a docs-only run (a services:
container starts with the job regardless of step if:), but the 787-migration replay — the expensive
part — is skipped.
Two adjacent redundancies are deliberately out of scope: the whole matrix re-running on a PR and
again on the merge-to-main over identical code (#420), and the within-run triple dotnet build
(#398). Full mechanism in ci-cd.md → "Docs-only skip".