diff --git a/LABELS.md b/LABELS.md index 61ffcfc..46a7f08 100644 --- a/LABELS.md +++ b/LABELS.md @@ -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 — 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 -hand-set state); the `labeled` event fires the sweep that validates the -write within seconds. +hand-set state). On a same-repository head, the `labeled` event fires the +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) diff --git a/docs/CONSUMERS.md b/docs/CONSUMERS.md index 6573fd5..6594eed 100644 --- a/docs/CONSUMERS.md +++ b/docs/CONSUMERS.md @@ -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 `state:*` axis on the board rather than a red workflow run. The labels 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 -event run goes red at the trigger. +repos included: the trigger job's dispatch is a write. Without it, issue and +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 -to a #209-carrying tag without adding the sweep caller keeps green-looking -silence nowhere — the trigger job goes **red on every PR and issue event** -(workflow-not-found; likewise on a sweep caller missing its `bootstrap` -input, or a labels caller missing `actions: write`), and event-woken sweeps -stop until the caller lands. That loudness is deliberate: never read -silence, or a green `scope` alone, as health. Make the adoption one atomic -PR — pin bump, sweep caller file, `actions: write` line together. +to a #209-carrying tag without adding the sweep caller gets a loud red trigger +on every issue and same-repository PR event (workflow-not-found; likewise on a +sweep caller missing its `bootstrap` input, or a labels caller missing +`actions: write`). Fork-headed PR runs deliberately skip that trigger and stay +green, so their correctness is proven by the sweep caller's presence and its +latest scheduled run, not by the PR check alone. Never read a green +`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 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 write. The sweep caller keeps `actions: read`. -Bump without the sweep caller and the trigger job goes red on every PR -and issue event — the loud failure mode above — so never split these -four edits across PRs. +Bump without the sweep caller and the trigger job goes red on every issue and +same-repository PR event; fork-headed PRs stay green but receive no labels +without the scheduled sweep. Never split these four edits across PRs. `pull_request_target` is intentional: same-repository PRs keep the base repository's write token without executing PR code. This Forgejo still gives