ci(416): skip heavy jobs on docs-only changes without bricking the merge gate #422

2026-07-17T19:19:39+02:00

timothy commented

2026-07-17 19:19:39 +02:00

Refs #416 (not fixes — the "verified on a real docs-only PR" Done-when box can only be ticked after this lands, since the gate takes effect on main; see below).

What

A docs-only change (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. This skips the heavy work without bricking the merge gate.

The trap, and why this shape

main's branch protection requires two contexts by name (Build & test (.NET), EF migration integrity (SQLite + MySql)). A workflow-level paths-ignore — or an if:-skipped required job — would produce no run for those contexts, so a docs-only PR could never merge. The naive fix bricks docs PRs.

I answered the issue's central open question empirically with a throwaway probe (now-closed PR #418): on Gitea 1.25.4 an if:-skipped job reports commit-status state skipped (a distinct state, not success). So this change does not if:-skip the required jobs.

How

New scripts/ci-detect-docs-only.sh emits docs_only=true|false. Each heavy job (test, migrations, functional-e2e, build) runs it as its first post-checkout step (id: detect) and gates every real step on docs_only != 'true'. The jobs always run and report success in seconds on docs-only → both required contexts keep reporting → docs-only PRs stay mergeable by construction. This is the same id: detect → step-if: pattern api-docs/format already use in production.

Non-required jobs may skip freely (production proves a skipped non-required context — build on every PR — doesn't block merge), so build also skips its image steps on a docs-only push to main.
Tag builds force docs_only=false — a release is never skipped.
Detection biases toward running more: docs_only=true only when every changed path is docs/** or *.md; any code path, tag, non-merge push, or undeterminable diff → full matrix. Uses --no-renames so a code→docs rename can't be misclassified (review finding).
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.

Verification done

Local: yaml parse, shellcheck clean, an 8-case detection test matrix (PR/push/tag/dispatch; docs-only vs code vs web vs workflow-yml vs code→docs-rename), decisions append-only guard.
Cold adversarial review: MERGEABLE; its one MEDIUM (rename misclassification) is fixed here via --no-renames.

Still to verify post-merge (why this is `Refs`, not `fixes`)

The gate only takes effect once on main. After merge I'll open (a) a docs-only PR and confirm both required contexts report green in seconds and it's mergeable, and (b) a .cs-only PR confirming the full matrix still runs — then tick the remaining Done-when boxes and close #416.

Docs

docs/ci-cd.md → new "Docs-only skip" section + triggers-table note; docs/decisions.md entry. The separate PR-vs-main-rerun redundancy your comment raised is filed as #420 (distinct from the within-run triple build, #398).

🤖 Generated with Claude Code

Refs #416 (not `fixes` — the "verified on a real docs-only PR" Done-when box can only be ticked *after* this lands, since the gate takes effect on `main`; see below). ## What A docs-only change (`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. This skips the heavy work **without** bricking the merge gate. ## The trap, and why this shape `main`'s branch protection requires two contexts **by name** (`Build & test (.NET)`, `EF migration integrity (SQLite + MySql)`). A workflow-level `paths-ignore` — or an `if:`-skipped required job — would produce **no run** for those contexts, so a docs-only PR could **never merge**. The naive fix bricks docs PRs. I answered the issue's central open question empirically with a throwaway probe (now-closed PR #418): on **Gitea 1.25.4** an `if:`-skipped job reports commit-status state **`skipped`** (a distinct state, not `success`). So this change does **not** `if:`-skip the required jobs. ## How New `scripts/ci-detect-docs-only.sh` emits `docs_only=true|false`. Each heavy job (`test`, `migrations`, `functional-e2e`, `build`) runs it as its first post-checkout step (`id: detect`) and gates **every real step** on `docs_only != 'true'`. The jobs **always run and report `success` in seconds** on docs-only → both required contexts keep reporting → docs-only PRs stay mergeable *by construction*. This is the same `id: detect` → step-`if:` pattern `api-docs`/`format` already use in production. - Non-required jobs may skip freely (production proves a `skipped` non-required context — `build` on every PR — doesn't block merge), so `build` also skips its image steps on a **docs-only push to `main`**. - **Tag builds force `docs_only=false`** — a release is never skipped. - Detection **biases toward running more**: `docs_only=true` only when *every* changed path is `docs/**` or `*.md`; any code path, tag, non-merge push, or undeterminable diff → full matrix. Uses `--no-renames` so a code→docs rename can't be misclassified (review finding). - `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. ## Verification done - Local: yaml parse, shellcheck clean, an 8-case detection test matrix (PR/push/tag/dispatch; docs-only vs code vs web vs workflow-yml vs code→docs-rename), decisions append-only guard. - Cold adversarial review: **MERGEABLE**; its one MEDIUM (rename misclassification) is fixed here via `--no-renames`. ## Still to verify post-merge (why this is `Refs`, not `fixes`) The gate only takes effect once on `main`. After merge I'll open (a) a docs-only PR and confirm both required contexts report green in seconds and it's mergeable, and (b) a `.cs`-only PR confirming the full matrix still runs — then tick the remaining Done-when boxes and close #416. ## Docs `docs/ci-cd.md` → new "Docs-only skip" section + triggers-table note; `docs/decisions.md` entry. The separate PR-vs-main-rerun redundancy your comment raised is filed as #420 (distinct from the within-run triple build, #398). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

timothy commented

2026-07-17 19:24:08 +02:00

Cold-context adversarial review (review-only agent, independent of implementation), then a re-review of the fix commit at the current head:

Merge-gate safety — confirmed safe by construction. Both required contexts (test, migrations) carry no job-level if:; they always run, gate only their steps, and report success in seconds on docs-only. Same id: detect → step-if: pattern api-docs/format already use in production.
Tag/release safety — a v* build can never be skipped (GITHUB_REF_TYPE=tag short-circuits to docs_only=false, same assumption the existing meta step relies on).
build meta outputs — every consumer of steps.meta.outputs.* is gated by the same condition, so nothing reads them while running.
One MEDIUM found and fixed: git diff --name-only has rename detection on by default, so a code→docs rename (Foo.cs→docs/Foo.md) would show only the destination and be misclassified as docs-only, skipping required tests on a code change. Fixed with --no-renames (empirically verified: the deletion Foo.cs now surfaces → full matrix). Re-review confirmed the fix is applied on the single changed-set git diff, closes the hole, and regresses nothing.

The only delta since the first review is that one-line hardening (folded into commit 1) plus the docs commit (no code).

Review-verdict: MERGEABLE @ 52b37614

Cold-context adversarial review (review-only agent, independent of implementation), then a re-review of the fix commit at the current head: - **Merge-gate safety — confirmed safe by construction.** Both required contexts (`test`, `migrations`) carry no job-level `if:`; they always run, gate only their steps, and report `success` in seconds on docs-only. Same `id: detect` → step-`if:` pattern `api-docs`/`format` already use in production. - **Tag/release safety** — a `v*` build can never be skipped (`GITHUB_REF_TYPE=tag` short-circuits to `docs_only=false`, same assumption the existing meta step relies on). - **build meta outputs** — every consumer of `steps.meta.outputs.*` is gated by the same condition, so nothing reads them while running. - **One MEDIUM found and fixed**: `git diff --name-only` has rename detection on by default, so a code→docs rename (`Foo.cs`→`docs/Foo.md`) would show only the destination and be misclassified as docs-only, skipping required tests on a code change. Fixed with `--no-renames` (empirically verified: the deletion `Foo.cs` now surfaces → full matrix). Re-review confirmed the fix is applied on the single changed-set `git diff`, closes the hole, and regresses nothing. The only delta since the first review is that one-line hardening (folded into commit 1) plus the docs commit (no code). Review-verdict: MERGEABLE @ 52b37614

timothy force-pushed ci/416-docs-only-skip from 52b37614cc to f7b97adce8

2026-07-17 19:44:49 +02:00

Compare

timothy commented

2026-07-17 19:45:11 +02:00

⚠️ Correction — the previous MERGEABLE @ 52b37614 was against a commit that did NOT contain the --no-renames fix. Process error on my side: the fix was applied in the working tree and empirically verified there, but never committed before the first push (index/worktree mismatch), so 52b37614 — and the CI that ran on it — still had the rename hole, and the re-review confirmed my working tree rather than the pushed commit.

Fixed properly now:

--no-renames is committed (verified on the pushed commit, not just the working tree — 3 occurrences in scripts/ci-detect-docs-only.sh).
Rebased onto current main (ffa8e5a0, past #419); diff is exactly the 4 intended files, no unrelated changes.
New head: f7b97adc. Superseded verdict @ 52b37614 is void; a fresh verdict @ f7b97adc follows once CI is green and the reviewer confirms the pushed commit.

⚠️ **Correction — the previous `MERGEABLE @ 52b37614` was against a commit that did NOT contain the `--no-renames` fix.** Process error on my side: the fix was applied in the working tree and empirically verified there, but never committed before the first push (index/worktree mismatch), so `52b37614` — and the CI that ran on it — still had the rename hole, and the re-review confirmed my working tree rather than the pushed commit. Fixed properly now: - `--no-renames` is committed (verified on the **pushed** commit, not just the working tree — 3 occurrences in `scripts/ci-detect-docs-only.sh`). - Rebased onto current `main` (`ffa8e5a0`, past #419); diff is exactly the 4 intended files, no unrelated changes. - New head: **`f7b97adc`**. Superseded verdict `@ 52b37614` is void; a fresh verdict `@ f7b97adc` follows once CI is green and the reviewer confirms the pushed commit.

timothy commented

2026-07-17 19:46:04 +02:00

Re-review of the pushed commit f7b97adc (verified against git show f7b97adc:…, not the working tree, given the earlier mismatch):

Committed script carries the fix — line 80 git diff --no-renames --name-only "$range" is in the pushed object.
Diff is exactly the 4 intended files; no #419 revert leakage.
Step-gating unchanged (32 docs_only != 'true' guards); only material change vs. the reviewed content is the committed --no-renames hardening.

Review-verdict: MERGEABLE @ f7b97adc

Re-review of the **pushed commit** `f7b97adc` (verified against `git show f7b97adc:…`, not the working tree, given the earlier mismatch): - Committed script carries the fix — line 80 `git diff --no-renames --name-only "$range"` is in the pushed object. - Diff is exactly the 4 intended files; no #419 revert leakage. - Step-gating unchanged (32 `docs_only != 'true'` guards); only material change vs. the reviewed content is the committed `--no-renames` hardening. Review-verdict: MERGEABLE @ f7b97adc

timothy referenced this pull request

2026-07-17 20:07:13 +02:00

CI: docs-only changes run the full build/test matrix (~9 min) for nothing #416

timothy merged commit 9c72aebab0 into main

2026-07-17 20:10:25 +02:00

timothy deleted branch ci/416-docs-only-skip

2026-07-17 20:10:25 +02:00

timothy referenced this issue from a commit

2026-07-17 20:10:26 +02:00

Merge pull request 'ci(416): skip heavy jobs on docs-only changes without bricking the merge gate' (#422) from ci/416-docs-only-skip into main

timothy referenced this pull request

2026-07-17 22:01:04 +02:00