fix(746): drop the persisted checkout credential; unmask the base-ref fetches
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)

`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
This commit is contained in:
2026-08-26 20:08:28 +02:00
parent 40a3232d9e
commit 4196a057fb
9 changed files with 201 additions and 36 deletions
+2
View File
@@ -40,6 +40,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
- name: Setup .NET
uses: actions/setup-dotnet@v4
+26 -4
View File
@@ -124,6 +124,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
- name: Resolve the pinned toolchain tag in the registry
env:
ETV_REGISTRY_AUTH: ${{ secrets.REGISTRY_USER }}:${{ secrets.REGISTRY_PASSWORD }}
@@ -147,6 +149,7 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
# git history/tags are needed by the `build` job's `git describe` (ersatztv#190) and,
# here, by the #420 revalidate step's `HEAD^2` tree comparison on a main merge commit.
fetch-depth: 2
@@ -419,6 +422,7 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
# was the default fetch-depth: 1 (ersatztv#190); bumped to 2 so the #420 revalidate
# step's `HEAD^2` tree comparison can resolve on a main merge commit.
fetch-depth: 2
@@ -585,6 +589,7 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
# bumped from 1 (ersatztv#190 default) so the #420 revalidate step's `HEAD^2` tree
# comparison can resolve on a main merge commit.
fetch-depth: 2
@@ -727,6 +732,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@v5
with:
@@ -800,6 +807,7 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
fetch-depth: 0
# ersatztv#416: a docs-only push to main has nothing to rebuild (docs are not in the image),
@@ -986,14 +994,21 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
fetch-depth: 0
- name: Detect API-surface changes
id: detect
run: |
base_ref="${{ github.base_ref }}"
git fetch --no-tags --depth=100 origin "$base_ref" || true
changed="$(git diff --name-only "origin/${base_ref}...HEAD" 2>/dev/null || true)"
if ! git fetch --no-tags origin "$base_ref"; then
echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository."
exit 1
fi
if ! changed="$(git diff --name-only "origin/${base_ref}...HEAD")"; then
echo "::error::git diff against origin/${base_ref} failed, so the changed-file set could not be computed — do not read this as 'nothing changed' (ersatztv#746). If it reports no merge base, rebase this branch onto ${base_ref}."
exit 1
fi
echo "Changed files in this PR:"; printf '%s\n' "$changed"
if printf '%s\n' "$changed" | grep -Eq '^ErsatzTV/Controllers/Api/|^ErsatzTV\.Core/Api/'; then
echo "api_changed=true" >> "$GITHUB_OUTPUT"
@@ -1081,14 +1096,21 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
fetch-depth: 0
- name: Detect changed C# files
id: detect
run: |
base_ref="${{ github.base_ref }}"
git fetch --no-tags --depth=100 origin "$base_ref" || true
changed="$(git diff --name-only --diff-filter=ACM "origin/${base_ref}...HEAD" -- '*.cs' 2>/dev/null || true)"
if ! git fetch --no-tags origin "$base_ref"; then
echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository."
exit 1
fi
if ! changed="$(git diff --name-only --diff-filter=ACM "origin/${base_ref}...HEAD" -- '*.cs')"; then
echo "::error::git diff against origin/${base_ref} failed, so the changed-file set could not be computed — do not read this as 'nothing changed' (ersatztv#746). If it reports no merge base, rebase this branch onto ${base_ref}."
exit 1
fi
echo "Changed .cs files in this PR:"; printf '%s\n' "$changed"
if [ -n "$changed" ]; then
printf '%s\n' "$changed" > /tmp/changed-cs.txt
+31 -5
View File
@@ -62,6 +62,7 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
# need real history: `git log -- <path>` on a shallow clone can't find the last
# commit that touched the image sources
fetch-depth: 0
@@ -138,12 +139,26 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
fetch-depth: 0
# `continue-on-error` for the same reason the two steps below carry it: this whole job
# is a non-blocking nudge, and an advisory red still joins the combined status the merge gate
# reads. Unmasking the fetch (ersatztv#746) makes a broken base LOUD in the log; it must not
# also make a warn-only job merge-blocking. The three jobs that genuinely gate on this diff —
# api-docs, format, decisions lifecycle — do redden on a failed fetch, which is where that
# belongs.
- name: Warn when a screen/route change skips the parity doc
continue-on-error: true
run: |
base_ref="${{ github.base_ref }}"
git fetch --no-tags --depth=100 origin "$base_ref" || true
changed="$(git diff --name-only "origin/${base_ref}...HEAD" 2>/dev/null || true)"
if ! git fetch --no-tags origin "$base_ref"; then
echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository."
exit 1
fi
if ! changed="$(git diff --name-only "origin/${base_ref}...HEAD")"; then
echo "::error::git diff against origin/${base_ref} failed, so the changed-file set could not be computed — do not read this as 'nothing changed' (ersatztv#746). If it reports no merge base, rebase this branch onto ${base_ref}."
exit 1
fi
echo "Changed files in this PR:"; printf '%s\n' "$changed"
screen_or_route=no
if printf '%s\n' "$changed" | grep -Eq '^web/src/screens/.+\.tsx$|^ErsatzTV/LegacyUiRedirects\.cs$'; then
@@ -169,7 +184,8 @@ jobs:
# python-using job on it declares this. Without it a missing interpreter is exit 127 — a RED
# advisory job joining the combined status, which is the one thing this step must never be.
#
# Both steps carry `continue-on-error` because the SCRIPT exiting 0 is not the whole invariant:
# Both steps OF THIS CHECK (setup-python + the narrative step; the parity nudge above has its
# own) carry `continue-on-error` because the SCRIPT exiting 0 is not the whole invariant:
# a setup-python download failure reddens the job just as effectively as a hit would, and an
# advisory red still joins the combined status the merge gate reads (ersatztv#598). Scope,
# stated rather than implied: this covers the two steps that exist to run the check. A failed
@@ -186,7 +202,10 @@ jobs:
continue-on-error: true
run: |
base_ref="${{ github.base_ref }}"
git fetch --no-tags --depth=100 origin "$base_ref" || true
if ! git fetch --no-tags origin "$base_ref"; then
echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository."
exit 1
fi
python3 scripts/check-doc-narrative.py --diff "origin/${base_ref}"
# BLOCKING (ersatztv#521, supersedes the ersatztv#303 H9 append-only mechanic): validates decision-
@@ -204,6 +223,7 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
@@ -212,7 +232,10 @@ jobs:
- name: Validate decision lifecycle
run: |
base_ref="${{ github.base_ref }}"
git fetch --no-tags --depth=200 origin "$base_ref" || true
if ! git fetch --no-tags origin "$base_ref"; then
echo "::error::git fetch of origin/${base_ref} failed, so this job cannot compute the changed-file set it derives its work from. That is a broken job, not an empty change set (ersatztv#746). Check the base branch still exists and that the runner can reach the repository."
exit 1
fi
PYTHONPATH=. python3 scripts/decisions_validate.py --base "origin/${base_ref}" --head HEAD
- name: Active catalog in sync
run: PYTHONPATH=. python3 scripts/build_decisions_catalog.py --check
@@ -251,6 +274,7 @@ jobs:
# clone would leave it unable to resolve `<sha>^` and it would refuse every commit.
uses: actions/checkout@v4
with:
persist-credentials: false
fetch-depth: 0
- name: Set up Python
uses: actions/setup-python@v5
@@ -365,6 +389,8 @@ jobs:
steps:
- name: Checkout
uses: actions/checkout@v4
with:
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@v5
with:
+88 -7
View File
@@ -147,6 +147,83 @@ A backup, fetch, or migration-smoke failure aborts before the live container is
**Also avoid firing several pushes back-to-back** (e.g. a `[skip ci]` commit, then `main`, then a tag, all within ~1s). Observed once on this Gitea instance: the later events were silently dropped — no `ActionRun` records created at all, even though the runner was online and the workflow `active`. Pushing again, spaced out, created the runs normally. If a push/tag doesn't produce a run, re-push (or push an empty commit) rather than assuming the runner is broken.
## Checkouts drop the persisted credential (ersatztv#746)
Every `actions/checkout` in this repo **except `ci-image.yml`'s** (see the carve-out below) sets
`persist-credentials: false`. Without it the action leaves an `Authorization` header in
`.git/config`, and a head-resolved job then hands that credential to every script it runs, not just
to the checkout. That header is write-capable: this instance's Actions default token permission is
`permissive`, where it stands after a Restricted trial was reverted on 2026-08-05, and flipping it
back is ersatztv#748. No job that checks out
loses anything: none of them push with git, and anonymous access covers the fetches because the repo
is public — `private: false`, and `GET /info/refs?service=git-upload-pack` answers unauthenticated,
measured 2026-08-26 from the LAN. That measures the repository, not a runner's network path to it,
and the runner path is deliberately not asserted here: it does not need to be, because the fetches
in the jobs below are unmasked: an anonymous fetch that failed from a runner reddens `api-docs`,
`Formatting` and `decisions lifecycle` instead of being swallowed. (The two masked fetches further
down are covered by their own argument, not by this one.) Renovate does push branches, but
`renovate.yml` has no `actions/checkout` step at all and carries its own `RENOVATE_TOKEN`.
The base-ref fetches that feed the changed-file skip logic — in `docs-reminder`, `decisions
lifecycle`, `api-docs` and `Formatting` — therefore run **unmasked**: a failed `git fetch` — and a failed
`git diff` at the three steps that run one inline — exit the step with an `::error::` instead of
yielding an empty changed set. That ordering is the general rule, not a fact about one
change: unmask a dependent fetch *before* you drop a persisted credential anywhere. Under `|| true`
a credential regression looked like "nothing changed" on the three steps that also masked
`git diff`, so those checks skipped themselves silently on a green job; on the other two it handed
a possibly-absent `origin/<base>` to a Python validator. Neither shape is one you want a credential
change to land on top of.
**What this does and does not make fail-closed.** A failed *fetch* now reddens `api-docs`,
`Formatting` and `decisions lifecycle`, which is the credential/network case this change exists for.
It does not make the two validator steps fail-closed in general: they run no inline `git diff`, and
if the base resolves badly despite a successful fetch, `scripts/decisions_validate.py` emits a
`::warning::` and skips its diff-dependent checks while `scripts/check-doc-narrative.py` prints
`SCANNED NOTHING` and exits 0. Both fail open there by their own design and are out of scope here —
do not read a green `decisions lifecycle` as proof its diff-dependent checks ran. Note which side of
that line the `Decisions-Edit: yes` trailer check falls on: `_edit_trailer_armed` is reached only
after the merge base resolves, so it goes quiet with the rest of them rather than surviving.
**Loud is not the same as blocking, and the split is by job.** `api-docs`, `Formatting` and
`decisions lifecycle` gate on this diff, so a failed fetch reddens them. `docs-reminder` does not —
it is a non-blocking nudge, and an advisory red still joins the combined status the merge gate
reads. All three of its non-checkout steps therefore carry `continue-on-error: true` — the parity
nudge, `Set up Python` and the doc-narrative warning — so the `::error::` reaches the log without
turning a warning into a merge block. `Checkout` is deliberately still blocking; with no tree there
is nothing to warn about.
**None of these fetches passes `--depth`.** All five run in jobs that check out `fetch-depth: 0`,
and `git fetch --depth=N` on a *complete* clone grafts it shallow: the history is still there but
cut off, so `git diff origin/<base>...HEAD` fails with `no merge base` once the branch point is
further back than N. Measured 2026-08-26: a 150-commit repo branched 130 back, `--depth=100`,
`.git/shallow` created, three-dot diff `fatal: no merge base`; the same fetch without `--depth`
returns the correct file list. Under the old `|| true` that surfaced as a silent skip; unmasked it
would have reddened `api-docs` and `Formatting` on any branch not rebased recently, sent
`docs-reminder`'s parity nudge advisory-red, and left `decisions lifecycle` green with its
diff-dependent checks silently skipped — so the depth came off with the mask. The same graft is why `:latest` images ship `InformationalVersion 0.0.0-<sha>` (ersatztv#836).
**Two masked fetches that stay masked, deliberately.** `scripts/ci-detect-docs-only.sh` and
`scripts/ci-detect-already-validated.sh` both swallow a failed fetch — and should. In both, a failed
fetch can only leave the base revision unresolvable, and an unresolvable base emits `false`: *run
the full matrix / full validation*. Neither can turn a failed fetch into a skip. Masking there costs
runner time and nothing else, which is the opposite direction from the workflow steps above, where
the same masking bought a silently skipped check. Judge these by which way the failure falls, not by
the `|| true`.
That clears their **masking** and nothing else. Their `--depth` is a separate question with a
separate answer: `ci-detect-docs-only.sh`'s push-path `--depth=2` runs inside the `build` job's
`fetch-depth: 0` checkout and grafts it shallow, which is why the `git describe` in the immediately
following step returns nothing and `:latest` ships `InformationalVersion 0.0.0-<sha>` — measured on
the live test container as `0.0.0-5a7a4ed7` (ersatztv#836). That depth is correct for the script's
other three consumers — `test`, `migrations` and `functional-e2e` — whose checkouts really are
shallow (`fetch-depth: 2`). `build` is the only one that checks out complete, which is why it is the
only one that grafts.
**`ci-image.yml` is the one exception** and is tracked in ersatztv#744, which has to change that
file alone: any commit touching `.gitea/workflows/ci-image.yml` re-points `ci-image-pin`'s
`expected` at itself and reddens that blocking job, and the file's unfiltered `push` trigger
publishes a toolchain image from whatever branch the edit lands on.
## The workflow: `.gitea/workflows/docker-build.yml`
Single workflow. Gating jobs `test` + `migrations` run in parallel and gate `build`; a
@@ -427,9 +504,10 @@ the image build.
job (exit 137); excluding it cuts the instrumented surface ~126× (2.5M→20k coverable
lines in the whole-solution `Architecture.Tests` process) and makes the percentage reflect
authored code.
- **Shallow checkout**: `fetch-depth: 1` (ersatztv#190) — this job never runs `git
describe`/`git log`, only `build` needs full history/tags for version computation, so
`test` and `migrations` both check out shallow. `build`'s checkout stays `fetch-depth: 0`.
- **Shallow checkout**: `fetch-depth: 2` — this job never runs `git describe`/`git log`, and only
`build` needs full history/tags for version computation, so `test`, `migrations` and
`functional-e2e` all check out shallow. It was 1 (ersatztv#190) until ersatztv#420's revalidate
step needed `HEAD^2` to resolve on a main merge commit. `build`'s checkout stays `fetch-depth: 0`.
- **NuGet package cache**: both `test` and `migrations` cache `~/.nuget/packages` via
`actions/cache@v4`, keyed on `hashFiles('Directory.Packages.props', 'global.json')` with
a `restore-keys` OS-level fallback (ersatztv#190). Avoids a from-scratch `dotnet restore`
@@ -548,7 +626,8 @@ files) has nothing for the heavy jobs to validate. Before this, such a change ra
is gated `if: steps.detect.outputs.docs_only != 'true'`. On a docs-only change the job runs only
checkout + detect and **reports `success` in seconds**.
**Shallow-checkout safe (the change-set diff).** `test`/`migrations` check out `fetch-depth: 1`, and
**Shallow-checkout safe (the change-set diff).** `test`, `migrations` and `functional-e2e` all check
out shallow (`fetch-depth: 2`), and
a shallow clone has **no `origin/<base>` tracking ref and no merge-base** — so a three-dot
`origin/main...HEAD` diff *errors*, the fail-safe returns `docs_only=false`, and the skip silently
never fires (the first cut shipped this bug — every docs-only PR still ran the full matrix; caught by
@@ -867,9 +946,11 @@ exists for.
Because this step needs an interpreter, the job DOES carry `actions/setup-python` — the one
exception to the no-setup-actions note below, since `python3` is not guaranteed on the bare `small`
lane. Both it and the script step carry `continue-on-error: true`: a script that exits 0 does not by
itself keep the JOB green, and a setup-action download failure would redden an advisory check just
as effectively as a hit would.
lane. It, the script step and the parity-doc step above it all carry `continue-on-error: true`: a script
that exits 0 does not by itself keep the JOB green, a setup-action download failure would redden an
advisory check just as effectively as a hit would, and the parity step's base-ref fetch fails loudly
(ersatztv#746) — which must reach the log without reddening a warn-only job. `Checkout` is the one
step left blocking.
The job deliberately has **no** `setup-dotnet`/`setup-node` (and
thus no `actions/cache`), so it can't hit the cache-save hangs seen on the VM-127 runner
+1 -1
View File
@@ -37,7 +37,7 @@ the link for rationale. Superseded/retired history lives in `archive/`. Regenera
| `blazor.rollback-tag` | The commit immediately preceding the Blazor-removal merge is tagged `blazor-final` (not a `v*` tag, so it doesn't trigger a prod release build) as the documented rollback/restore path. | 2026-07-11 | [link](records/blazor/rollback-tag.md) |
| `blazor.ui-removed` | The legacy Blazor Server UI (`Pages/`, `Shared/`, `ViewModels/`, `Validators/`, MudBlazor + 8 other packages, Blazor Startup wiring) is fully deleted now that the SPA has parity; the legacy `MapWhen` branch is kept only for controllers/docs/OpenAPI/`LegacyUiRedirects`, and the catch-all fallback 302s any unmatched non-api/artwork/docs/openapi path to `/app`. | 2026-07-11 | [link](records/blazor/ui-removed.md) |
| `channel.origin-marker` | A new `Channel.Origin` (`ChannelOrigin` enum — `Unknown`/`UserCreated`/`AutoTuned`) records how a channel row was created and is stamped exactly once at insert (`AutoTuned` in `CreateChannelFromLineupHandler`, `UserCreated` in `CreateChannelHandler`), and is never mutated on a later edit. It is surfaced as a raw `origin` field on `ChannelResponseModel`; the SPA badges only `AutoTuned`. Rows predating the column read `Unknown` — provenance is **not** back-filled. | 2026-07-23 | [link](records/channel/origin-marker.md) |
| `ci.actions-credential-scoping` | Any credential reachable from an Actions job is scoped to what that job needs. The container-registry secret `REGISTRY_PASSWORD` is a personal access token scoped `write:package` + `read:repository` — never an account PASSWORD. This matters because Gitea has NO `status` token scope: `POST /repos/{o}/{r}/statuses/{sha}` is gated by `reqRepoWriter(unit.TypeCode)`, so ANY credential that can write the repository can forge `review-verdict/h10`, the required context that is supposed to make merge-consent derived rather than assertable. Package-write IS a separate scope, so the registry credential can be made status-incapable at no cost: `scripts/ci-detect-already-validated.sh` only GETs. Do NOT add a `permissions:` key to constrain the injected `GITEA_TOKEN` on the assumption that it binds — below Gitea 1.26.0 it is silently a NO-OP, which is worse than absent because it reads in review as a constraint. That version precondition NO LONGER HOLDS: this instance was upgraded 1.25.4 -> 1.27.1 on 2026-08-05. What has NOT changed is that the consequence is unverified — whether `permissions:` is honored here, and what this instance's default Actions token permission is, were both left UNPROBED (there is still no API surface: `/api/v1/settings/actions` 404s at 1.27.1). Probe before relying on it; do not read the upgrade alone as the constraint now working. Scoping is necessary and not sufficient: it bounds what a job may DO, never whether attacker YAML runs at all, so a self-referencing trigger needs its own filter (`ci-image.yml`, tracked in #744 — deliberately NOT bundled here, because editing that file re-points `ci-image-pin` at the editing commit and reddens a blocking job). This record closes ONE route. It does not close the class, and four later sections say exactly what survives — read them before citing this record as a mitigation. | 2026-08-05 | [link](records/ci/actions-credential-scoping.md) |
| `ci.actions-credential-scoping` | Any credential reachable from an Actions job is scoped to what that job needs. The container-registry secret `REGISTRY_PASSWORD` is a personal access token scoped `write:package` + `read:repository` — never an account PASSWORD. This matters because Gitea has NO `status` token scope: `POST /repos/{o}/{r}/statuses/{sha}` is gated by `reqRepoWriter(unit.TypeCode)`, so ANY credential that can write the repository can forge `review-verdict/h10`, the required context that is supposed to make merge-consent derived rather than assertable. Package-write IS a separate scope, so the registry credential can be made status-incapable at no cost: `scripts/ci-detect-already-validated.sh` only GETs. Do NOT add a `permissions:` key to constrain the injected `GITEA_TOKEN` on the assumption that it binds — below Gitea 1.26.0 it is silently a NO-OP, which is worse than absent because it reads in review as a constraint. That version precondition NO LONGER HOLDS: this instance was upgraded 1.25.4 -> 1.27.1 on 2026-08-05. What has NOT changed is that the consequence is unverified — whether `permissions:` is honored here is still UNPROBED, and there is still no API surface for it (`/api/v1/settings/actions` 404s at 1.27.1). The instance default HAS since been probed and is NOT unknown: it was set to Restricted, verified, and reverted to `permissive` on 2026-08-05 (#748), which is where it stands. Probe before relying on it; do not read the upgrade alone as the constraint now working. Scoping is necessary and not sufficient: it bounds what a job may DO, never whether attacker YAML runs at all, so a self-referencing trigger needs its own filter (`ci-image.yml`, tracked in #744 — deliberately NOT bundled here, because editing that file re-points `ci-image-pin` at the editing commit and reddens a blocking job). A second, separate consequence of the same boundary: `actions/checkout` persists a write-capable credential into `.git/config` unless `persist-credentials: false` is set, and 15 of this repo's 16 checkouts now set it (#746), `ci-image.yml`'s being excluded for the reason in that section. Ordering is part of the rule: unmask the dependent fetches FIRST, because until then a credential regression presents as an empty changed-file set and a silently skipped check rather than a red job. This record closes ONE route. It does not close the class, and the later sections say exactly what survives — read them before citing this record as a mitigation. | 2026-08-05 | [link](records/ci/actions-credential-scoping.md) |
| `ci.batch-pushes-no-cancel-route` | Hold review fixes, doc corrections and format fixes locally and push **once** — a superseded run cannot be cancelled from the agent side and holds a runner slot until it finishes. | 2026-07-21 | [link](records/ci/batch-pushes-no-cancel-route.md) |
| `ci.build-once-rejected` | CI build-once (a shared compile artifact across jobs) was implemented, measured, and rejected for a 40-85% wall-clock regression; keep the #420 cross-run tree-identity skip instead. | 2026-07-18 | [link](records/ci/build-once-rejected.md) |
| `ci.cancelled-is-not-a-verdict` | Treat a `cancelled` conclusion as "no verdict" — never as pass or fail — and report FAILED and CANCELLED counts separately in any CI monitor. THE COMBINED COMMIT-STATUS ENDPOINT CANNOT EXPRESS THIS: `GET /repos/{o}/{r}/commits/{sha}/status` has states `success`/`failure`/`pending`/`error` and NO `cancelled`, so it reports a cancelled job as `failure`. Anything polling that endpoint — which is what a CI monitor naturally polls, because it is the per-sha view the merge gate reads — must resolve the job-level `conclusion` via `actions/runs/{id}/jobs` before reporting a red. | 2026-07-21 | [link](records/ci/cancelled-is-not-a-verdict.md) |
@@ -5,8 +5,8 @@ status: active
since: '2026-08-05'
supersedes: none
superseded-by: none
rule: 'Any credential reachable from an Actions job is scoped to what that job needs. The container-registry secret `REGISTRY_PASSWORD` is a personal access token scoped `write:package` + `read:repository` — never an account PASSWORD. This matters because Gitea has NO `status` token scope: `POST /repos/{o}/{r}/statuses/{sha}` is gated by `reqRepoWriter(unit.TypeCode)`, so ANY credential that can write the repository can forge `review-verdict/h10`, the required context that is supposed to make merge-consent derived rather than assertable. Package-write IS a separate scope, so the registry credential can be made status-incapable at no cost: `scripts/ci-detect-already-validated.sh` only GETs. Do NOT add a `permissions:` key to constrain the injected `GITEA_TOKEN` on the assumption that it binds — below Gitea 1.26.0 it is silently a NO-OP, which is worse than absent because it reads in review as a constraint. That version precondition NO LONGER HOLDS: this instance was upgraded 1.25.4 -> 1.27.1 on 2026-08-05. What has NOT changed is that the consequence is unverified — whether `permissions:` is honored here, and what this instance''s default Actions token permission is, were both left UNPROBED (there is still no API surface: `/api/v1/settings/actions` 404s at 1.27.1). Probe before relying on it; do not read the upgrade alone as the constraint now working. Scoping is necessary and not sufficient: it bounds what a job may DO, never whether attacker YAML runs at all, so a self-referencing trigger needs its own filter (`ci-image.yml`, tracked in #744 — deliberately NOT bundled here, because editing that file re-points `ci-image-pin` at the editing commit and reddens a blocking job). This record closes ONE route. It does not close the class, and four later sections say exactly what survives — read them before citing this record as a mitigation.'
signals: 'admin password in CI secrets, registry credential scope, ETV_STATUS_AUTH can write statuses, forge review-verdict/h10, head-resolved workflow holds credentials, Gitea token scopes, no status scope, write:package vs write:repository, permissions key no-op, GITEA_TOKEN default read/write, Restricted default token permissions, orphan secret, deploy key in secret store, toolchain image overwrite, prod floating tag write · paths: `.gitea/workflows/docker-build.yml`, `.gitea/workflows/ci-image.yml`, `.gitea/workflows/renovate.yml`, `scripts/ci-detect-already-validated.sh` · issues: #697, #672, #698, #742, #743, #420, server-management#714'
rule: 'Any credential reachable from an Actions job is scoped to what that job needs. The container-registry secret `REGISTRY_PASSWORD` is a personal access token scoped `write:package` + `read:repository` — never an account PASSWORD. This matters because Gitea has NO `status` token scope: `POST /repos/{o}/{r}/statuses/{sha}` is gated by `reqRepoWriter(unit.TypeCode)`, so ANY credential that can write the repository can forge `review-verdict/h10`, the required context that is supposed to make merge-consent derived rather than assertable. Package-write IS a separate scope, so the registry credential can be made status-incapable at no cost: `scripts/ci-detect-already-validated.sh` only GETs. Do NOT add a `permissions:` key to constrain the injected `GITEA_TOKEN` on the assumption that it binds — below Gitea 1.26.0 it is silently a NO-OP, which is worse than absent because it reads in review as a constraint. That version precondition NO LONGER HOLDS: this instance was upgraded 1.25.4 -> 1.27.1 on 2026-08-05. What has NOT changed is that the consequence is unverified — whether `permissions:` is honored here is still UNPROBED, and there is still no API surface for it (`/api/v1/settings/actions` 404s at 1.27.1). The instance default HAS since been probed and is NOT unknown: it was set to Restricted, verified, and reverted to `permissive` on 2026-08-05 (#748), which is where it stands. Probe before relying on it; do not read the upgrade alone as the constraint now working. Scoping is necessary and not sufficient: it bounds what a job may DO, never whether attacker YAML runs at all, so a self-referencing trigger needs its own filter (`ci-image.yml`, tracked in #744 — deliberately NOT bundled here, because editing that file re-points `ci-image-pin` at the editing commit and reddens a blocking job). A second, separate consequence of the same boundary: `actions/checkout` persists a write-capable credential into `.git/config` unless `persist-credentials: false` is set, and 15 of this repo''s 16 checkouts now set it (#746), `ci-image.yml`''s being excluded for the reason in that section. Ordering is part of the rule: unmask the dependent fetches FIRST, because until then a credential regression presents as an empty changed-file set and a silently skipped check rather than a red job. This record closes ONE route. It does not close the class, and the later sections say exactly what survives — read them before citing this record as a mitigation.'
signals: 'admin password in CI secrets, registry credential scope, ETV_STATUS_AUTH can write statuses, forge review-verdict/h10, head-resolved workflow holds credentials, persist-credentials on actions/checkout, credential left in .git/config, masked git fetch yields empty changed set, Gitea token scopes, no status scope, write:package vs write:repository, permissions key no-op, GITEA_TOKEN default read/write, Restricted default token permissions, orphan secret, deploy key in secret store, toolchain image overwrite, prod floating tag write · paths: `.gitea/workflows/docker-build.yml`, `.gitea/workflows/pr-checks.yml`, `.gitea/workflows/dependency-scan.yml`, `.gitea/workflows/ci-image.yml`, `.gitea/workflows/renovate.yml`, `scripts/ci-detect-already-validated.sh` · issues: #697, #672, #698, #742, #743, #746, #748, #835, #420, server-management#714'
mechanics: 'PAT `ci-registry-scoped-697`, scopes `write:package,read:repository`, stored as repo Actions secret `REGISTRY_PASSWORD`; `REGISTRY_USER` remains `timothy`. Verified 2026-08-05 on Gitea 1.25.4: registry push of a probe tag SUCCEEDED; `GET /commits/{sha}/status` 200; `POST /statuses/{sha}` REFUSED HTTP 403 `token does not have at least one of required scope(s), required=[write:repository], token scope=write:package,read:repository`. Probe artifacts deleted, confirmed 404. NOT measured with this token: the `container:` pull, the buildcache write and the base-image pull. Those rest on Gitea''s scope model (write implies read per category, read at tag `v1.25.4`) — INFERRED. Note WHICH run proves which: only the `container:` pull is exercised by a PR. `cache-to`/`cache-from` and the base-image pull are confined to the `build` job, which carries `if: github.event_name != ''pull_request''`, so they are first exercised on the post-merge push to `main` — AFTER the merge gate has passed. A wrong inference there reddens main, not the PR.'
---
@@ -51,8 +51,37 @@ code can no longer escalate to instance admin — NOT that the durable forgery r
bound — auditing it rather than the workflow set is what found `RENOVATE_TOKEN` and
`SERVERMGMT_DEPLOY_KEY` below, since any PR-added workflow can reference any secret. But
`GITEA_TOKEN` is injected and never in the store; nor is the credential
`actions/checkout` persists into `.git/config` (`docker-build.yml` omits `persist-credentials: false`);
and jobs reach the runner's docker daemon.
`actions/checkout` persists into `.git/config` (dropped on 15 of the repo's 16 checkouts in #746;
`ci-image.yml` is excluded and is head-resolved in the sense that matters — see below); and jobs
reach the runner's docker daemon.
**The persisted checkout credential (#746).** `actions/checkout` writes an `Authorization` header
into `.git/config` unless `persist-credentials: false` is set, so a job hands that credential to
every script it runs, not only to the checkout — and it is 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). 15 of the repo's 16 checkouts
now set it: `docker-build.yml` (8), `pr-checks.yml` (5), `dependency-scan.yml` (1) and
`review-verdict.yml` (1, pre-existing). No job that checks out pushes with git, so none of them
loses a capability; `renovate.yml` does push, but has no checkout step and uses `RENOVATE_TOKEN`.
**Unmask the dependent fetches BEFORE dropping a persisted credential** — the rule, not a note about
one change. Five steps fed `git fetch ... origin "$base_ref" || true` into changed-file skip logic,
where a credential regression reddens nothing: on the three that also masked `git diff` it yields an
empty changed set the skip logic reads as "nothing changed", and on the other two it hands a
possibly-absent `origin/<base>` to a validator. Anonymous fetch does cover this repo (public; `git-upload-pack` answers
unauthenticated, measured 2026-08-26), which is a reason to make the failure loud rather than a
reason to trust it silently. The same step is where `--depth` came off those fetches: their jobs
check out `fetch-depth: 0`, and `git fetch --depth=N` grafts a complete clone shallow, so a
three-dot diff against a branch point further back than N fails `no merge base` — invisible under
`|| true`, and without it a red `api-docs`/`Formatting` (`decisions lifecycle` would stay green with
its diff-dependent checks skipped, because its validator fails open on an unresolvable base).
`ci-image.yml`'s single checkout is the one exception, and NOT because it is safe: its unfiltered
`push` trigger makes it head-resolved in the sense that matters. It is excluded because editing that
file re-points `ci-image-pin`'s `expected` at the editing commit and reddens a blocking job, and
because the same trigger would publish a toolchain image from the editing branch. It rides with
#744, which exists to change that file alone. #835 tracks the guard for this convention: it can only
be written without an exemption list once #744 has landed.
**Measured vs inferred.** Measured here: the `v1.25.4` scope enum (`access_token_scope.go`) has no
`status` entry; the `reqRepoWriter` gate (`routers/api/v1/api.go`); the probes in `mechanics`. Read from
@@ -69,9 +98,12 @@ re-probing. Re-verification of the 1.25.4-pinned claims across the CI docs is tr
**Surviving routes — this record is not a mitigation for any of them.** `RENOVATE_TOKEN` is a
`write:repository` bot PAT in the same store, posting with a real creator, and cannot be scoped down
because Renovate needs repo write (#742). The injected `GITEA_TOKEN` is write-capable in every job;
only Gitea >=1.26 with the Actions default set to **Restricted** binds it (server-management#714) —
the version half of that condition is now satisfied (1.27.1) but the *default* half is unverified, so
treat this route as still open until probed. A
only Gitea >=1.26 with the Actions default set to **Restricted** binds it (server-management#714).
Both halves of that condition have now been checked and it does not hold, because of the second one:
the version half IS satisfied (1.27.1), while the default was set to Restricted, verified, and
reverted to `permissive` on 2026-08-05 because this repo is not ready for it (#748). So the route is
open, and open for a known reason rather than an unprobed one — waiting on a further Gitea upgrade
would be waiting on the wrong thing. A
collaborator's own token always can. `docker-build.yml` publishes `:prod` from a `v*` tag push and a tag
may point at ANY commit — a prod image with no PR, review or status (tag protections are empty).
**And none of it was necessary: direct pushes to `main` were server-side permitted, so the gate was
@@ -11,7 +11,9 @@ mechanics: '`docs/ci-cd.md` → "Docs-only skip"; verified via a real shallow `f
---
The #416 docs-only skip shipped (#422) safe but **ineffective**: every docs-only PR still ran the full
matrix. Root cause — `test`/`migrations` check out `fetch-depth: 1`, and in a shallow clone
matrix. Root cause — the consumer jobs check out shallow (`fetch-depth: 1` then, 2 now, and the
consumers are `test`, `migrations` and `functional-e2e`; both depths are shallow, so the rule is
unaffected by the change), and in a shallow clone
`origin/<base>` has no remote-tracking ref and there is no merge-base, so the detect script's
three-dot `git diff origin/main...HEAD` errored → `|| true` → empty diff → the fail-safe returned
`docs_only=false` → full matrix. Confirmed in a real shallow `file://` clone (`origin/main` did not
@@ -60,16 +60,15 @@ rather than assumed: from one worktree, the branch push to `main` was refused an
Do not conflate the two mechanisms — disabling branch push says nothing about tags, and a future
tag-protection rule would not inherit from this one.
**The `docker-build.yml` `persist-credentials` question (#743's fourth box), decided and deferred.**
Its six `actions/checkout` steps omit `persist-credentials: false`, so a head-resolved job keeps a
write-capable credential in `.git/config`. It *should* be set — but not blind, and not in this PR,
because two steps run `git fetch --no-tags --depth=100 origin "$base_ref" || true` and feed the result
into the changed-file skip logic. That `|| true` means a credential regression does not fail the job;
it silently yields an empty changed-file set, and the skip logic then reads "nothing changed". The repo
is public, so anonymous fetch is *expected* to cover it — expected is not measured, and the failure
mode is silent, which is the shape that has burned this repo before. The correct order is: drop the
`|| true` masking so a fetch failure is loud, then set `persist-credentials: false` and confirm both
jobs still compute a non-empty changed set on a PR that genuinely changes files.
**The `docker-build.yml` `persist-credentials` question (#743's fourth box), since resolved in #746.**
Head-resolved jobs kept a write-capable credential in `.git/config` because their `actions/checkout`
steps omitted `persist-credentials: false`. Setting it was right but not safe to do blind, and the
ordering is the part worth keeping, as a rule for the next time: unmask the dependent fetches first,
then set the flag. Under `|| true` a credential regression does not fail the job — it yields an empty
changed-file set that the skip logic reads as "nothing changed". The population is also wider than the
six checkouts #743 recorded: eight in `docker-build.yml`, five in `pr-checks.yml`, one in
`dependency-scan.yml`, plus `review-verdict.yml`'s pre-existing one — 15 of the repo's 16. Details in
`ci.actions-credential-scoping`.
**Why this is not redundant with the Husky pre-push hooks.** `.husky/pre-push` guards (H6 done-when,
H11 rebase, H13 clean worktree) are client-side and deliberately fail-open — a git hook cannot prompt.
+2 -1
View File
@@ -38,7 +38,8 @@ if [ "${GITHUB_REF_TYPE:-}" = "tag" ]; then
fi
# Resolve a concrete BASE COMMIT to diff HEAD against. SHALLOW-CHECKOUT SAFE (ersatztv#416
# follow-up): the `test`/`migrations` jobs check out `fetch-depth: 1`, and a shallow clone has NO
# 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