fix(672): review round 1 -- pin the trigger set exactly, sweep the stale claims

Cold review found the first cut of the test satisfiable by a still-vulnerable
config, and two prose claims that outran the evidence.

The test asserted "pull_request_target present, pull_request absent". Adding
`workflow_dispatch:` or `push:` ALONGSIDE it kept that green, and both are
ref-resolved with secrets, so either one restores an equivalent
self-supplied-definition path. Enumerating those two would have the same hole one
trigger later, so the assertion now pins the whole set: exactly
{pull_request_target}, nothing else. Verified by mutation -- adding
`workflow_dispatch` now reds.

Adds the guard that would have caught the residual below rather than only the
instance: no workflow OTHER than review-verdict.yml may reference
`review-verdict/h10` in executable lines. Scoped honestly in its docstring as a
drift guard, not a security boundary -- a workflow can still write the status
through an indirection a text scan cannot see.

`release.verdict-status-check` item 4 still asserted, in the present tense, that
a PR editing review-verdict.yml is judged by its own edited copy. That is now
false for this workflow, and it is the record a reader resolving the gate from
the catalog actually lands on. Past-tensed, with the surviving residual named.

The probe count said three. There were four; the omitted one is the only one with
a negative result, which is what turns an honest partial into an overclaim.
Corrected in both the record and ci-cd.md, along with what was NOT measured
(`reopened`/`ready_for_review` firing under the new trigger).

Also records two operational consequences a maintainer will otherwise hit cold:
retargeting a PR onto `main` leaves it statusless until its next push (`edited`
is not in `types:`), and the required contexts carry a literal `(pull_request)`
suffix, so repeating this fix on docker-build.yml would rename them and deadlock
merges unless branch protection is edited in the same operation.

Trimmed the record back under the 60-line prose ceiling -- for the second time
this session, which is ersatztv#688 reproducing, not a defect here.

Refs: #672
Refs: #697
Decisions-Edit: yes
This commit is contained in:
2026-07-28 21:49:22 +02:00
parent 8b73234d78
commit 35a8ea8aef
4 changed files with 96 additions and 54 deletions
+5 -2
View File
@@ -812,12 +812,15 @@ Three properties of this workflow are security-relevant and are pinned by tests
trigger merely moves the rewrite to an attacker-pushed base — and a status forged there is
inherited by any later PR carrying the same head sha (ersatztv#663). `pull_request_target` is safe
here **only** because this job never checks out or executes head-supplied code. Verified on this
instance with three scratch PRs rather than inferred from GitHub; full rationale in
instance with four scratch PRs rather than inferred from GitHub; full rationale in
`docs/decisions/records/ci/gate-trigger-base-resolved.md`. **This closes the rewrite route through
this workflow, not the class:** `docker-build.yml` is also head-resolved and its `ETV_STATUS_AUTH`
credentials can write statuses, so it can still forge `review-verdict/h10` — it must stay on
`pull_request` because it builds the PR's code, so it needs a read-only status identity instead
(ersatztv#697).
(ersatztv#697). One operational consequence: a PR whose base is not `main` now gets **no**
`review-verdict/h10` at all. That is fail-closed, but `edited` is not among the trigger's `types`,
so a PR opened against another base and later **retargeted** onto `main` stays statusless until its
next push — if a retargeted PR looks stalled with the check simply missing, that is why.
- **The checkout takes the PR's BASE ref**, `ref: ${{ github.event.pull_request.base.sha }}` with
`persist-credentials: false` — never the head. This job judges the PR, so the PR must not supply
the code that judges it; a head checkout would let a PR edit the enumeration to return an empty
@@ -11,37 +11,37 @@ mechanics: '`on: pull_request_target: {branches: [main], types: [opened, reopene
---
`ci.shared-pr-file-enumeration` established that this job checks out the PR's **base** ref so the PR
cannot supply the *scripts* that judge it. That binding was real but partial, and the record said so:
it does not bind the job **definition**. This record closes the remaining half.
cannot supply the *scripts* that judge it — a real but partial binding, as that record said: it does
not bind the job **definition**. This closes the remaining half.
**What was actually wrong.** Gitea, like GitHub, resolves a `pull_request` workflow definition from
the PR's own head commit. A PR editing `review-verdict.yml` therefore ran its own rewritten copy,
which could delete the base checkout or skip straight to posting `review-verdict/h10=success` for its
head sha. Two things that look like they should have prevented it did not: `PROTECTED` is defined by
the same rewritten file, and branch protection requires the *context*, not an author, while carrying
`required_approvals: 0`.
the PR's own head, so a PR editing `review-verdict.yml` ran its own rewritten copy — which could
delete the base checkout or skip straight to posting `review-verdict/h10=success` for its head sha.
Two things that look preventive were not: `PROTECTED` is defined by the same rewritten file, and
branch protection requires the *context*, not an author, while carrying `required_approvals: 0`.
**Measured, not inferred.** The premise is a claim about someone else's software, so it was settled
on this instance (Gitea 1.25.4) with three scratch PRs rather than by analogy to GitHub. A PR
rewriting the workflow to post a distinct probe context posted exactly that context, and the real
`review-verdict/h10` was never written — the base's definition never ran at all. Under
`pull_request_target` the identical rewrite was ignored: the base definition ran and posted
`h10=pending`, on both `opened` and `synchronize`, with `secrets` still available. With
`branches: [main]` added, a PR into a non-`main` base produced no run and no status whatsoever. The
probes posted only probe-named contexts, never a forged `h10`.
on this instance (Gitea 1.25.4) with **four** scratch PRs, not by analogy to GitHub. A PR rewriting
the workflow posted its own probe context and the real `review-verdict/h10` was never written — the
base definition never ran. Under `pull_request_target` the identical rewrite was ignored: the base
definition ran and posted `h10=pending`, on `opened` and `synchronize` alike, with `secrets` still
available. With `branches: [main]`, a PR into a non-`main` base produced no run and no status at all.
The fourth probe is the negative one that established the residual below; it is counted because
omitting it is what turns an honest partial into an overclaim. The probes posted only probe-named
contexts, never a forged `h10`. Not measured: whether `reopened`/`ready_for_review` fire here.
**Why `branches: [main]` is load-bearing rather than tidy.** Base resolution means the *base branch*
supplies the definition. Dropping the filter would trade a head-supplied gate for a base-supplied one
and close nothing, because anyone who can push a branch can make that branch a base. It is worse than
a lateral move: a commit status is repo-global per sha (`#663`), so a `success` forged against a
scratch base is **inherited** by a later, genuine PR into `main` carrying the same head. The filter is
what keeps "the base" and "`main`" the same thing.
supplies the definition, and anyone who can push a branch can make it a base — so dropping the filter
trades a head-supplied gate for a base-supplied one and closes nothing. Worse than lateral: a commit
status is repo-global per sha (`#663`), so a `success` forged against a scratch base is **inherited**
by a later genuine PR into `main` with the same head. The filter keeps "the base" and "`main`" the
same thing.
**Why `pull_request_target` is not the footgun it usually is.** Its standard danger is executing
untrusted head code with a privileged token. This job executes none: it checks out `base.sha` with
`persist-credentials: false` and runs only scripts from that tree. The trigger and the base-ref
checkout are therefore one decision and must be read together — under this trigger, a head checkout
would hand a privileged token to PR-supplied code, which is strictly worse than #672 was.
`persist-credentials: false` and runs only that tree's scripts. Trigger and checkout are therefore
one decision — under this trigger a head checkout would hand a privileged token to PR-supplied code,
strictly worse than #672 was.
**Options not taken.** `required_approvals: 1` was the cheapest mechanical fix and is unusable here:
Gitea forbids approving your own PR and this is effectively a single-maintainer repo, so it would
@@ -54,17 +54,19 @@ authority can be asserted by the thing it judges is not a gate — not because a
**The class is NOT closed, and this record must not be read as claiming otherwise.** The bug fixed
here is one instance of "a head-resolved workflow holds credentials that can POST a commit status."
`docker-build.yml` is another: it triggers on `pull_request`, so it is head-resolved, and it carries
`ETV_STATUS_AUTH` (`REGISTRY_USER:REGISTRY_PASSWORD`) for the #420 revalidation read. Basic auth is
not scoped, so an account that can read statuses can write them — confirmed by the same probe method,
with a probe-named context, not asserted. A PR rewriting `docker-build.yml` can therefore still post
`review-verdict/h10=success` for its own head. That workflow **must** stay head-resolved, because it
builds and tests the PR's code; `pull_request_target` there would be the genuine footgun. It needs a
read-only status identity instead, tracked in `#697`. Stated here rather than left implicit because
the predecessor record's specific documented failure was a reassuring sentence in the position a
catalog reader stops at.
`docker-build.yml` is another: head-resolved (`on: pull_request`), carrying `ETV_STATUS_AUTH`
(`REGISTRY_USER:REGISTRY_PASSWORD`) for the #420 revalidation read. Basic auth is not scoped, so an
account that can read statuses can write them — confirmed by probe, not asserted. A PR rewriting it
can still post `review-verdict/h10=success` for its own head, and it **must** stay head-resolved
because it builds the PR's code, so it needs a read-only status identity instead (`#697`). Stated
here rather than implied because the predecessor record's documented failure was a reassuring
sentence in exactly the position a catalog reader stops at.
**Residual.** The job's own status context is renamed to `... (pull_request_target)` by the switch.
That is safe only because it was never one of branch protection's required contexts, which remain the
two `docker-build.yml` job contexts plus `review-verdict/h10`; adding it would let the workflow
satisfy the gate merely by running. The per-sha inheritance property behind `#663` is untouched here.
**Residual.** The job's own context is renamed to `... (pull_request_target)`, safe only because it
was never one of branch protection's required contexts (the two `docker-build.yml` contexts plus
`review-verdict/h10`); adding it would let the workflow satisfy the gate by merely running. **A trap
for #697:** those two carry the literal suffix `(pull_request)`, so giving `docker-build.yml` the
same treatment renames them and deadlocks every merge unless branch protection is edited in the same
operation. A PR based off a non-`main` branch now gets no status where it previously got one —
fail-closed, and it removes a `#663` inheritance hazard — but `edited` is absent from `types:`, so a
PR retargeted onto `main` stays statusless until its next `synchronize`.
@@ -172,15 +172,21 @@ described as one:
gate earlier in the hook. That carve-out does not auto-grant — it passes through to an ordinary
permission prompt — so the exposure is a missing warning on a merge a human is already confirming,
not a silent merge. Worth knowing before reading "the hook denies on a retarget" as unconditional.
4. **A PR that edits `review-verdict.yml` is judged by its own edited copy.** Gitea runs
`pull_request` workflows from the PR **head**, not the base — confirmed on the very PR that
introduced this workflow (#630): `review-verdict.yml` does not exist on `main`, yet its job ran
and posted a status. So `PROTECTED` is a guardrail against *accidental* self-exemption, **not** a
tamper-proof control: a PR that rewrote the workflow would be classified by the rewritten rules.
Acceptable for a two-account repo (`timothy`, `renovate`) where the threat is a careless change
rather than a hostile one; it would not be for an untrusted-contributor repo, which would need
the classification moved somewhere the PR cannot edit (a base-branch-pinned workflow, or
server-side policy).
4. **A PR that edits `review-verdict.yml` WAS judged by its own edited copy — closed in #672, see
`ci.gate-trigger-base-resolved`.** Gitea runs `pull_request` workflows from the PR **head**, not
the base — confirmed on the very PR that introduced this workflow (#630): `review-verdict.yml`
does not exist on `main`, yet its job ran and posted a status. `PROTECTED` was therefore a
guardrail against *accidental* self-exemption, **not** a tamper-proof control: a PR that rewrote
the workflow would be classified by the rewritten rules. The workflow now triggers on
`pull_request_target` scoped to `branches: [main]`, so its definition is taken from the base.
**Only this file's instance is closed, not the class.** Any head-resolved workflow holding
credentials that can POST a commit status can still forge `review-verdict/h10`;
`docker-build.yml` demonstrably can, and must stay head-resolved because it builds the PR's own
code. Tracked in #697. So the "careless change rather than a hostile one" posture below still
describes the repo accurately — it is simply no longer *this* workflow that is the weakest link.
An untrusted-contributor repo would still need the classification moved somewhere no PR can
reach (server-side policy), not merely a base-pinned definition.
The same head-execution behaviour is what makes the rollout self-hosting in the good case: #630's
own run correctly identified it as touching `.claude/` and `scripts/`, refused both exemptions,
+39 -8
View File
@@ -528,14 +528,16 @@ def test_the_workflow_trigger_is_pull_request_TARGET_scoped_to_main():
trigger is ADDED back alongside it.
"""
on = _workflow_triggers()
assert "pull_request_target" in on, (
"review-verdict.yml must trigger on `pull_request_target`; under plain `pull_request` "
"Gitea takes the workflow DEFINITION from the PR head, so a PR can rewrite the gate that "
"judges it (ersatztv#672)")
assert "pull_request" not in on, (
"review-verdict.yml still carries a plain `pull_request` trigger — that runs the "
"head-supplied definition, which is exactly the ersatztv#672 hole, and it would run "
"ALONGSIDE the safe one rather than replacing it")
# EXACT SET, not "target present and plain absent". Cold review found the weaker pair of
# assertions green after ADDING `workflow_dispatch:` or `push:` alongside the safe trigger —
# both are ref-resolved and both get secrets, so either one restores an equivalent
# self-supplied-definition path while the test reports clean. Enumerating the two known-bad
# extra triggers would have the same hole one trigger later; pinning the whole set does not.
assert set(on) == {"pull_request_target"}, (
f"review-verdict.yml must trigger on `pull_request_target` and NOTHING else; got "
f"{sorted(map(str, on))}. Plain `pull_request` takes the workflow DEFINITION from the PR "
"head (ersatztv#672), and `push`/`workflow_dispatch` resolve it from an arbitrary ref — "
"any of them, ADDED ALONGSIDE rather than replacing, reopens the hole")
branches = (on["pull_request_target"] or {}).get("branches")
assert branches == ["main"], (
@@ -544,6 +546,35 @@ def test_the_workflow_trigger_is_pull_request_TARGET_scoped_to_main():
"into an attacker-pushed base run that branch's rewritten copy (ersatztv#672)")
def test_no_OTHER_workflow_writes_the_review_verdict_status():
"""`review-verdict.yml` is the only workflow allowed to write `review-verdict/h10`.
The trigger test above hardens ONE file, and by construction cannot see the more general
problem: the gate is forgeable by *any* head-resolved workflow holding credentials that can POST
a commit status, not only by the gate's own definition. `docker-build.yml` is exactly that — it
triggers on `pull_request` (correctly; it builds the PR's code) and carries `ETV_STATUS_AUTH`,
which a probe confirmed can WRITE statuses, not merely read them. That residual is tracked in
ersatztv#697 and is NOT closed by this test.
What this test does close is the cheap regression: a second workflow quietly starting to write
the context. It is a guard against drift, not a security boundary — a workflow can still write
the status through an indirection this scan cannot see (a variable, a script it calls). Said
plainly so nobody reads a green here as "only one writer is possible".
"""
offenders = []
for wf in sorted((REPO_ROOT / ".gitea" / "workflows").glob("*.yml")):
if wf.name == WORKFLOW.name:
continue
# CODE lines only — `docs`-style commentary in a workflow header legitimately discusses the
# context by name, and a raw-text scan would red on the prose explaining this very rule.
if "review-verdict/h10" in _code_lines(wf):
offenders.append(wf.name)
assert not offenders, (
f"{offenders} reference `review-verdict/h10` in executable lines. Only review-verdict.yml "
"may write the gate's own status; another workflow doing so is a forgery path (see "
"ersatztv#697) or, at best, a second implementation of the gate that will drift")
def test_the_workflow_checks_out_the_BASE_ref_never_the_head():
"""The self-rewrite hole. This workflow judges the PR, so the PR must not supply the code that
judges it: checking out `head.sha` would let a PR rewrite `scripts/pr-changed-files.sh` to