docs(labels): qualify fork-head sweep guarantees

This commit is contained in:
codex-bot-andresmgsl 2026-08-25 00:09:13 +00:00
parent e639e67f09
commit 7690c15e1a
2 changed files with 20 additions and 14 deletions

View file

@ -27,8 +27,10 @@ and the reconciler recomputes it from GitHub's own facts.
`state:needs-human` means exactly one thing — a human could merge this now — `state:needs-human` means exactly one thing — a human could merge this now —
so it requires zero blockers and head-current approvals; anything less and so it requires zero blockers and head-current approvals; anything less and
the reconciler takes it back. The author sets it at handoff (the one the reconciler takes it back. The author sets it at handoff (the one
hand-set state); the `labeled` event fires the sweep that validates the hand-set state). On a same-repository head, the `labeled` event fires the
write within seconds. sweep that validates the write within seconds; on a fork head whose
`pull_request_target` token is read-only, validation waits for the scheduled
sweep cadence (#241).
## PR blockers — what is in the way? (facts, as many as apply) ## PR blockers — what is in the way? (facts, as many as apply)

View file

@ -482,17 +482,21 @@ repositories allow check data to be read regardless, but a private consumer
needs the explicit reads above; without them the failure appears as an empty needs the explicit reads above; without them the failure appears as an empty
`state:*` axis on the board rather than a red workflow run. The labels `state:*` axis on the board rather than a red workflow run. The labels
caller's `actions: write` is different — it is required everywhere, public caller's `actions: write` is different — it is required everywhere, public
repos included: the trigger job's dispatch is a write, and without it every repos included: the trigger job's dispatch is a write. Without it, issue and
event run goes red at the trigger. same-repository PR event runs go red at the trigger. Fork-headed PR runs do
not enter that write path on this Forgejo; they remain green and depend on a
healthy scheduled sweep.
**The failure mode to know before bumping**: a consumer that bumps its pin **The failure mode to know before bumping**: a consumer that bumps its pin
to a #209-carrying tag without adding the sweep caller keeps green-looking to a #209-carrying tag without adding the sweep caller gets a loud red trigger
silence nowhere — the trigger job goes **red on every PR and issue event** on every issue and same-repository PR event (workflow-not-found; likewise on a
(workflow-not-found; likewise on a sweep caller missing its `bootstrap` sweep caller missing its `bootstrap` input, or a labels caller missing
input, or a labels caller missing `actions: write`), and event-woken sweeps `actions: write`). Fork-headed PR runs deliberately skip that trigger and stay
stop until the caller lands. That loudness is deliberate: never read green, so their correctness is proven by the sweep caller's presence and its
silence, or a green `scope` alone, as health. Make the adoption one atomic latest scheduled run, not by the PR check alone. Never read a green
PR — pin bump, sweep caller file, `actions: write` line together. `fork_head` disposition as evidence that the scheduled sweep exists. Make the
adoption one atomic PR — pin bump, sweep caller file, and `actions: write` line
together.
The `issues:` trigger is available at `0.2.0` and later — `0.2.0` is the The `issues:` trigger is available at `0.2.0` and later — `0.2.0` is the
first tag carrying ceremony#32. A consumer pinned to `0.1.0` omits it. Adopt first tag carrying ceremony#32. A consumer pinned to `0.1.0` omits it. Adopt
@ -543,9 +547,9 @@ carrying the split:
`actions: read` today (crew does); the trigger job's dispatch is a `actions: read` today (crew does); the trigger job's dispatch is a
write. The sweep caller keeps `actions: read`. write. The sweep caller keeps `actions: read`.
Bump without the sweep caller and the trigger job goes red on every PR Bump without the sweep caller and the trigger job goes red on every issue and
and issue event — the loud failure mode above — so never split these same-repository PR event; fork-headed PRs stay green but receive no labels
four edits across PRs. without the scheduled sweep. Never split these four edits across PRs.
`pull_request_target` is intentional: same-repository PRs keep the base `pull_request_target` is intentional: same-repository PRs keep the base
repository's write token without executing PR code. This Forgejo still gives repository's write token without executing PR code. This Forgejo still gives