Files
ersatztv/scripts/ci-detect-docs-only.sh
T
timothy 4196a057fb
Build ErsatzTV Image / CI toolchain image resolves (pull_request) Successful in 10s
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 13s
PR Gates / Docs update reminder (pull_request) Successful in 16s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 22s
PR Gates / decisions lifecycle (pull_request) Successful in 17s
Review verdict / Set review-verdict status (pull_request_target) Successful in 16s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 16s
PR Gates / Script lint and tests (ruff + pytest) (pull_request) Successful in 5m12s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m35s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m20s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 5m56s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 7s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 5s
review-verdict/h10 Review-verdict: MERGEABLE @ 4196a05 (base: main)
fix(746): drop the persisted checkout credential; unmask the base-ref fetches
`actions/checkout` leaves an `Authorization` header in `.git/config` unless
`persist-credentials: false` is set — write-capable while this instance's Actions
default token permission is `permissive`, where it stands after a Restricted trial
was reverted on 2026-08-05 (#748). Every workflow here except `review-verdict.yml`
omitted it, so a job handed that credential to every script it ran, not merely to the
checkout. 15 of the repo's 16 checkouts now set it.

Setting the flag first would have been unsafe, which is why #743 deferred it rather
than doing it blind: five steps ran `git fetch ... origin "$base_ref" || true` and
fed the result into changed-file skip logic, so a credential regression would have
presented as an empty changed set on the three steps that also masked `git diff`, and
a possibly-absent `origin/<base>` handed to a fail-open Python validator on the other
two — a silently self-skipping check on a green job either way.
So the masking comes out first, and only then does the flag go on. `git diff`'s own
`2>/dev/null || true` goes with it on the three sites that had one.

`--depth` came off those five fetches in the same step, and that is the part the cold
reviews converged on. All five run in jobs that check out `fetch-depth: 0`, and
`git fetch --depth=N` grafts a *complete* clone shallow — measured on a 150-commit
repo branched 130 back: `.git/shallow` appears and `git diff origin/main...HEAD` fails
`fatal: no merge base`, while the same fetch without `--depth` returns the correct
file list. Under `|| true` that was a silent skip; unmasked it would have reddened
`api-docs` and `format` on any branch not rebased inside the depth window, and left
`decisions lifecycle` green with its diff-dependent checks silently skipped.

Loud is not the same as blocking. `api-docs`, `format` and `decisions lifecycle` gate
on this diff and now redden on a failed fetch. `docs-reminder` does not — it is a
non-blocking nudge whose advisory red would still join the combined status the merge
gate reads, which is why its `Set up Python` and doc-narrative steps already carried
`continue-on-error: true`. The parity nudge now carries it for the same reason, so all
three of its non-checkout steps have it and the `::error::` reaches the log without
becoming a merge block. `Checkout` stays blocking.

The population is wider than #746's file list. Sweeping the shape rather than the
named file found 8 checkouts in `docker-build.yml` (not the six #743 recorded), 5 in
`pr-checks.yml` and 1 in `dependency-scan.yml`, and three masked fetches in
`pr-checks.yml` beside the two in `docker-build.yml`. That widening is recorded on the
issue so acceptance is judged against what shipped. No job that checks out pushes with
git, and the repo is public with anonymous `git-upload-pack` answering, so nothing
loses a capability it was using. Renovate does push branches, but `renovate.yml` has
no checkout step and carries its own `RENOVATE_TOKEN`.

Two further masked fetches, in `scripts/ci-detect-docs-only.sh` and
`scripts/ci-detect-already-validated.sh`, keep their masking on purpose: in both, a
failed fetch can only leave the base revision unresolvable, and an unresolvable base
emits `false` — run the full matrix. Neither can turn a failed fetch into a skip.
Their `--depth` is a different matter and is NOT cleared here: the push-path
`--depth=2` grafts the `build` job's `fetch-depth: 0` checkout, which is why `:latest`
images ship `InformationalVersion 0.0.0-<sha>` — measured on the live test container
as `0.0.0-5a7a4ed7` and filed as #836. Four stale statements of that script's
shallow-consumer set (two in docs/ci-cd.md, one in the script itself, one in
`ci.docs-only-detect-shallow-safe`) said `fetch-depth: 1` and named two of the three
consumers; they are corrected here, because this change states the same fact
again and would otherwise leave the corpus disagreeing with itself.

`ci-image.yml`'s one checkout is the exception, and not because it is safe: its
unfiltered `push` trigger is head-resolved in the sense that matters. It is excluded
because any commit touching that file re-points `ci-image-pin`'s `expected` at itself
and reddens a blocking job, and because the same trigger would publish a toolchain
image from the editing branch. It rides with #744.

No machine-checked guard holds the convention yet: writing one now means a hardcoded
`ci-image.yml` exemption whose only justification is a temporary condition in another
issue, and that entry would outlive its reason silently. Filed as #835, blocked by
#744, to be written with no exemption list at all.

fixes #746

Decisions-Edit: yes
2026-08-26 20:08:28 +02:00

127 lines
5.9 KiB
Bash
Executable File

#!/usr/bin/env bash
# scripts/ci-detect-docs-only.sh — emit `docs_only=true|false` to $GITHUB_OUTPUT for the
# docker-build.yml heavy-job gate (ersatztv#416). A change is "docs" iff every changed path is
# under docs/ or is a *.md file anywhere. docs_only=true ONLY when EVERY changed path is docs;
# any code path, an undeterminable diff, a tag build, or a non-PR/push event => false (run the
# full matrix).
#
# The bias is ALWAYS toward running MORE, never less: a false 'true' would skip the real
# test/migrations/build work on a code change, so every ambiguous case resolves to
# docs_only=false. It is fine (just wasteful) to run the full matrix on a docs change; it is a
# correctness bug to skip it on a code change.
#
# Why this is the merge-gate-safe half of #416: the two REQUIRED contexts (`Build & test (.NET)`,
# `EF migration integrity (SQLite + MySql)`) are gated by SKIPPING STEPS inside a job that always
# runs and always reports `success` — never by an `if:`-skipped job. On Gitea 1.25.4 an
# `if:`-skipped job reports commit-status state `skipped` (verified, PR #418), and how branch
# protection treats a `skipped` REQUIRED context is not something we rely on. Non-required jobs may
# skip freely (production already proves a `skipped` non-required context — e.g. `build` on every
# PR — does not block merge).
#
# Runs identically locally and in CI. Locally (no $GITHUB_OUTPUT) it prints the decision to stdout;
# e.g. GITHUB_EVENT_NAME=pull_request GITHUB_BASE_REF=main scripts/ci-detect-docs-only.sh
set -euo pipefail
out="${GITHUB_OUTPUT:-/dev/stdout}"
event="${GITHUB_EVENT_NAME:-}"
emit() {
echo "docs_only=$1" >> "$out"
echo "-> docs_only=$1"
}
# A release tag must NEVER be treated as docs-only, whatever it touches.
if [ "${GITHUB_REF_TYPE:-}" = "tag" ]; then
echo "tag build (${GITHUB_REF_NAME:-?}); never docs-only"
emit false
exit 0
fi
# Resolve a concrete BASE COMMIT to diff HEAD against. SHALLOW-CHECKOUT SAFE (ersatztv#416
# follow-up): the `test`/`migrations`/`functional-e2e` jobs check out shallow (`fetch-depth: 2`), and
# a shallow clone has NO
# `origin/<base>` remote-tracking ref and no merge-base — so the old `origin/<base>...HEAD`
# (three-dot) errored, the diff came back empty, and EVERY docs-only PR silently ran the full
# matrix (safe but useless). `git fetch` ALWAYS writes FETCH_HEAD (the fetched base tip), which
# resolves even in a shallow clone; we diff against it with a TWO-dot tree diff below (no merge-base
# required). Verified in a real shallow `file://` clone. (`api-docs`/`format` only worked because
# they use `fetch-depth: 0`.)
base_rev=""
case "$event" in
pull_request)
base="${GITHUB_BASE_REF:-}"
if [ -z "$base" ]; then
echo "pull_request with no base ref; running full matrix (safe default)"
emit false
exit 0
fi
if ! git fetch --no-tags --depth=200 origin "$base" 2>/dev/null; then
echo "fetch of base '$base' failed; running full matrix (safe default)"
emit false
exit 0
fi
base_rev="$(git rev-parse --verify -q FETCH_HEAD || true)"
;;
push)
# Only branch pushes reach here (tags handled above). Skip only when the range is UNAMBIGUOUS —
# HEAD is a merge commit (how every update to main lands): its first parent is the pre-merge
# tip, so HEAD^1 is the base. Fetch depth 2 so the first-parent tree exists in the shallow
# checkout; if it still can't be resolved/diffed we fall through to the full matrix. A non-merge
# (direct/multi-commit) push is ambiguous here -> full matrix.
git fetch --no-tags --depth=2 origin "${GITHUB_REF_NAME:-main}" 2>/dev/null || true
nfields="$(git rev-list --parents -n1 HEAD 2>/dev/null | wc -w | tr -d ' ')" # 1 (self) + parents
if [ "${nfields:-0}" -ge 3 ]; then
base_rev="$(git rev-parse --verify -q 'HEAD^1' || true)"
else
echo "non-merge push (parents=$(( nfields - 1 ))); running full matrix (safe default)"
emit false
exit 0
fi
;;
*)
echo "event '${event:-<none>}' is not pull_request/push; running full matrix (safe default)"
emit false
exit 0
;;
esac
if [ -z "$base_rev" ]; then
echo "could not resolve a base revision (shallow/offline); running full matrix (safe default)"
emit false
exit 0
fi
# TWO-dot tree diff `git diff <base> HEAD` (NOT three-dot) so no merge-base is needed — that is what
# makes this work in a shallow checkout. `--no-renames` is load-bearing: with rename detection ON
# (git's default) a code->docs rename (e.g. Foo.cs -> docs/Foo.md) shows ONLY the destination
# `docs/Foo.md`, hiding that a source file left the build -> misclassified as docs-only -> required
# tests skipped on a code change. --no-renames surfaces the deletion (`Foo.cs`, non-docs) so it
# correctly forces the full matrix, keeping the "any code path => run everything" invariant total.
changed="$(git diff --no-renames --name-only "$base_rev" HEAD 2>/dev/null || true)"
echo "Base: $base_rev (event=$event)"
echo "Changed files:"
printf '%s\n' "$changed"
if [ -z "$changed" ]; then
echo "empty/undeterminable diff; running full matrix (safe default)"
emit false
exit 0
fi
# docs_only unless SOME changed path is NOT docs. "docs" = under docs/ OR ends in .md (anywhere:
# README.md, CLAUDE.md, AGENTS.md, docs/handoffs/*.md, ...). Everything else — .cs, web/**,
# .gitea/**, Dockerfiles, scripts, csproj — is a code change and forces the full matrix.
#
# Capture the non-docs lines and test for emptiness rather than `grep -qv`: the combination of
# `-q` and `-v` early-exits inconsistently across grep implementations (BSD grep on macOS returned
# the wrong exit code here). `|| true` guards `set -e` when grep matches nothing (exit 1).
nondocs="$(printf '%s\n' "$changed" | grep -vE '(^docs/|\.md$)' || true)"
if [ -n "$nondocs" ]; then
echo "non-docs path(s) present in the diff -> NOT docs-only:"
printf '%s\n' "$nondocs" | sed 's/^/ /'
emit false
else
echo "every changed path is docs/ or *.md -> docs-only"
emit true
fi