From 07907456454642ab911c4c4277c1b57702e542c3 Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl Date: Tue, 25 Aug 2026 03:56:57 +0000 Subject: [PATCH] fix: qualify fork label coverage --- .github/workflows/labels-sweep.yml | 8 +++-- .github/workflows/labels.yml | 23 +++++++++----- .github/workflows/self-labels-sweep.yml | 11 ++++--- .github/workflows/self-labels.yml | 8 +++-- changelog.d/241.md | 2 +- docs/CONSUMERS.md | 42 +++++++++++++++---------- test/labels-triggers.test.sh | 41 +++++++++++------------- 7 files changed, 77 insertions(+), 58 deletions(-) diff --git a/.github/workflows/labels-sweep.yml b/.github/workflows/labels-sweep.yml index 7e2e3a1..0546978 100644 --- a/.github/workflows/labels-sweep.yml +++ b/.github/workflows/labels-sweep.yml @@ -5,8 +5,9 @@ name: labels-sweep # (workflow_dispatch plus the hourly cron, which relocated here with the # sweep). Issue events and same-repository PR events still yield a sweep within # seconds: labels.yml's trigger job dispatches this workflow's caller on those -# events. Fork-headed PR events carry a read-only token on this Forgejo and -# wait for the caller's scheduled cadence instead (#241). +# events. Fork-headed PR events carry a read-only token on this Forgejo, so +# state, blocker, and handoff reconciliation waits for the caller's scheduled +# cadence; the sweep does not apply path-derived scope labels (#241). # # Detached on purpose (#209): every sweep covers every open PR and all # sweeps serialize through ONE shared concurrency group, so GitHub's @@ -25,7 +26,8 @@ name: labels-sweep # taxonomy (its `bootstrap` input defaults to "yes"), exactly what # dispatching the labels caller did before the split. The trigger job's # dispatches carry bootstrap=no — ~20 label upserts per sweep is too chatty -# for every board event, the same reason cron runs never bootstrapped. +# for every issue and same-repository PR wake, the same reason cron runs never +# bootstrapped. # # This cannot loop: reconciler writes use GITHUB_TOKEN, and GitHub does not # create workflow runs from GITHUB_TOKEN-raised events (the trigger's diff --git a/.github/workflows/labels.yml b/.github/workflows/labels.yml index 7a2f864..f206a85 100644 --- a/.github/workflows/labels.yml +++ b/.github/workflows/labels.yml @@ -5,11 +5,13 @@ name: labels # The caller uses pull_request_target, not pull_request, so same-repository PRs # keep the base repository's write token without running PR code. On this # Forgejo, unlike GitHub, fork-headed _target runs still receive a read-only -# token. Those runs therefore attempt no writes and leave labeling to the -# scheduled sweep; the explicit fork_head job below records that disposition -# as a successful check. Both write paths execute only for same-repository -# heads. Scope reads changed paths and the path mapping through the API and -# checks out only the ceremony implementation. Keep it that way (#241). +# token. Those runs therefore attempt no writes. The scheduled sweep later +# reconciles state, blockers, and handoff, but it does not apply path-derived +# scope labels; consumers that require those labels on fork heads apply them +# manually. The explicit fork_head job below records that disposition as a +# successful check. Both write paths execute only for same-repository heads. +# Scope reads changed paths and the path mapping through the API and checks out +# only the ceremony implementation. Keep it that way (#241). # # The reconcile sweep lived here until #209. Riding the PR-triggered run # meant every displacement in the sweep's shared concurrency queue recorded @@ -26,7 +28,8 @@ name: labels # the surface that used to run reconcile directly. Same-repository wake latency # (#137) remains seconds-scale, while a displaced sweep cancels on the Actions # tab, attached to no PR. Fork-headed runs cannot dispatch with their read-only -# token, so their labels arrive on the scheduled sweep cadence. PR checks show +# token, so state, blocker, and handoff reconciliation waits for the scheduled +# sweep; path-derived scope labels are not applied to fork heads. PR checks show # scope + trigger for same-repository heads, or fork_head for fork heads. # # This cannot loop: the trigger's dispatch and the reconciler's label @@ -115,7 +118,8 @@ jobs: # The sweep's instant wake (#209) keeps the whole non-PR event surface and # same-repository PRs. Fork-headed PRs are excluded because this Forgejo # gives their pull_request_target run a read-only token (#241); fork_head - # records the successful deferral to the scheduled sweep instead. + # records which reconciliation waits for the sweep and that path-derived + # scope labels are not applied there. # # LOUD on failure — never `|| true`: a red trigger is the # misconfiguration alarm. A consumer that bumps the pin without adding @@ -205,6 +209,9 @@ jobs: echo "labels: sweep dispatched — $SWEEP_WORKFLOW on $branch (bootstrap=no)" fork_head: + # This Forgejo keeps pull_request_target read-only for fork heads (#241), + # so name the deliberately unsupported scope write as well as the deferred + # state machine instead of letting a green no-op promise full labelling. if: >- github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name != github.repository @@ -212,4 +219,4 @@ jobs: steps: - name: explain deferred fork labels run: >- - echo "labels: fork head has a read-only token; writes deferred to the scheduled sweep cadence" + echo "labels: fork head has a read-only token; state, blocker, and handoff reconciliation deferred to the scheduled sweep; path-derived scope labels are not applied to fork heads" diff --git a/.github/workflows/self-labels-sweep.yml b/.github/workflows/self-labels-sweep.yml index cb04ebe..53842c9 100644 --- a/.github/workflows/self-labels-sweep.yml +++ b/.github/workflows/self-labels-sweep.yml @@ -11,11 +11,12 @@ on: # pull_request_review trigger on the labels caller), blocker:ci-red set or # cleared (no check_suite/check_run/workflow_run), a blocker:conflict when # ANOTHER PR merges under this one, and the time-based stale / 48h - # claim-reclaim, plus every fork-headed PR transition on this Forgejo because - # its pull_request_target token is read-only (#241). Issue events and - # same-repository PR events carry the rest in seconds, one trigger-job - # dispatch away. Hourly trades ≤1h of latency on the scheduled classes - # while cutting nominal scheduled sweeps from four an hour to one at + # claim-reclaim, plus every state, blocker, and handoff transition for a + # fork-headed PR on this Forgejo because its pull_request_target token is + # read-only (#241). The sweep never applies path-derived scope labels. Issue + # events and same-repository PR events carry the rest in seconds, one + # trigger-job dispatch away. Hourly trades ≤1h of latency on the scheduled + # classes while cutting nominal scheduled sweeps from four an hour to one at # GitHub's 1-minute billing floor. Do not delete the cron: it is their # discovery path. If another engine writes some of those transitions, only # the classes with no other writer bound the cadence; relax it only as that diff --git a/.github/workflows/self-labels.yml b/.github/workflows/self-labels.yml index cd1c6b2..44d1fbf 100644 --- a/.github/workflows/self-labels.yml +++ b/.github/workflows/self-labels.yml @@ -11,7 +11,9 @@ name: labels # hourly cron and the manual/bootstrap workflow_dispatch. Issue events and # same-repository PR events below still yield a sweep within seconds, one # dispatch hop later. Fork-headed PRs carry a read-only token on this Forgejo, -# so their successful labels run leaves writes to the hourly sweep (#241). +# so their successful labels run leaves state, blocker, and handoff +# reconciliation to the hourly sweep; path-derived scope labels are not +# applied to those heads (#241). on: # Narrowed (#199) to the actions that carry a queue-state change the hourly # cron cannot wait one cadence for — dropping only labeled/unlabeled/assigned/ @@ -30,7 +32,9 @@ on: pull_request_target: # These carry the head/draft/review facts the sweep derives state:* from. # Same-repository heads wake that sweep in seconds; fork heads cannot write - # with this Forgejo's read-only token and wait for its scheduled cadence. + # with this Forgejo's read-only token, so state, blocker, and handoff + # reconciliation waits for the scheduled cadence. The sweep does not apply + # path-derived scope labels to those heads (#241). # labeled/unlabeled are the same-repository handoff wake — the author's # optimistic state:needs-human write, confirmed or corrected here in # seconds (#11); synchronize re-derives on every push; review_requested/ diff --git a/changelog.d/241.md b/changelog.d/241.md index 8c52d7e..fb68d29 100644 --- a/changelog.d/241.md +++ b/changelog.d/241.md @@ -1,3 +1,3 @@ ### Fixed -- Fork-headed label runs now stay green without attempting writes their read-only token cannot make, while same-repository heads keep instant labeling (#241). +- Fork-headed label runs stay green without attempting forbidden writes, while same-repository heads keep instant scope and reconciliation wakes (#241). diff --git a/docs/CONSUMERS.md b/docs/CONSUMERS.md index 6594eed..e25621e 100644 --- a/docs/CONSUMERS.md +++ b/docs/CONSUMERS.md @@ -345,8 +345,10 @@ together at the same pin: one of the two documented exemptions from the token's no-retrigger rule, so no PAT anywhere in the path and no loop: the sweep dispatches nothing). On this Forgejo a fork-headed `pull_request_target` token is - read-only, so those two jobs do not run; a successful `fork_head` job names - the deferral, and the scheduled sweep owns their labels. + read-only, so those two jobs do not run. A successful `fork_head` job names + the disposition: the scheduled sweep later reconciles state, blockers, and + handoff, while path-derived `scope:*` labels are not applied to fork heads. + Apply those scope labels manually when an outside contribution needs them. - **`labels-sweep.yml`** — the reconcile sweep: PR state, blockers, handoff, stale status, the issue work queue, and the `needs-ruling` invariants on both surfaces — the bare-flag check and the 7-day @@ -360,7 +362,8 @@ together at the same pin: Behind its own caller, a displaced sweep cancels on the Actions tab, attached to no PR. Same-repository PR checks show `scope` and the green `trigger`; fork-headed PRs show the green `fork_head` disposition - and wait for the scheduled sweep cadence. + and wait for scheduled state, blocker, and handoff reconciliation. The sweep + does not supply their path-derived scope labels. The consumer keeps its path mapping in `.github/labeler.yml` and its review panel plus scope taxonomy in `.github/labels.conf`. @@ -389,7 +392,9 @@ on: pull_request_target: # These carry the head/draft/review facts state:* derives from. Same-repo # heads take the instant write + sweep-dispatch path; this Forgejo gives - # fork heads a read-only token, so they wait for the scheduled sweep. + # fork heads a read-only token, so state, blocker, and handoff reconciliation + # waits for the scheduled sweep; path-derived scope labels require a manual + # write when wanted. # labeled/unlabeled are the same-repo handoff wake; synchronize re-derives # on every push. review_requested/review_request_removed shipped in 0.3.0 # (ceremony#137) and wake the same-repo sweep when the panel is asked. @@ -432,9 +437,10 @@ on: # wake for a review verdict landing (no # pull_request_review trigger on the labels caller), blocker:ci-red # set/cleared, blocker:conflict when another PR merges under this one, and - # time-based stale / 48h claim-reclaim, plus every fork-headed PR transition - # on this Forgejo. Issue events and same-repo PR - # events carry the rest in seconds, one trigger-job dispatch away. Hourly + # time-based stale / 48h claim-reclaim, plus every state, blocker, and handoff + # transition for a fork-headed PR on this Forgejo. The sweep never applies + # path-derived scope labels. Issue events and same-repo PR events carry the + # rest in seconds, one trigger-job dispatch away. Hourly # trades ≤1h of latency on the scheduled classes while cutting nominal # sweeps from four an hour to one at GitHub's 1-minute floor. Do not delete # the cron: it is their discovery path. If another engine writes some of @@ -443,9 +449,9 @@ on: schedule: [{cron: "0 * * * *"}] # A manual full-board sweep. A bare dispatch (input default "yes") also # bootstraps the taxonomy on a fresh repo. The labels caller's trigger job - # wakes this workflow with bootstrap=no on every issue and same-repo PR event, so the - # declared input is part of the contract: a dispatch naming an undeclared - # input is refused, and the trigger job goes loudly red. + # wakes this workflow with bootstrap=no on every issue and same-repo PR + # event, so the declared input is part of the contract: a dispatch naming an + # undeclared input is refused, and the trigger job goes loudly red. workflow_dispatch: inputs: bootstrap: @@ -485,7 +491,8 @@ caller's `actions: write` is different — it is required everywhere, public 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. +healthy scheduled sweep for state, blocker, and handoff reconciliation. That +sweep does not apply their path-derived scope labels. **The failure mode to know before bumping**: a consumer that bumps its pin to a #209-carrying tag without adding the sweep caller gets a loud red trigger @@ -548,14 +555,17 @@ carrying the split: write. The sweep caller keeps `actions: read`. 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. +same-repository PR event. Fork-headed PRs stay green, receive state, blocker, +and handoff reconciliation only from the scheduled sweep, and never receive +path-derived scope labels automatically; apply those manually when wanted. +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 -fork-headed `_target` runs a read-only token, so they attempt no writes and -leave labels to the scheduled sweep. The reusable workflows check out only the -consumer's base branch and the pinned ceremony implementation. +fork-headed `_target` runs a read-only token, so they attempt no writes. The +scheduled sweep later reconciles state, blockers, and handoff; it does not +apply path-derived scope labels to those heads. The reusable workflows check +out only the consumer's base branch and the pinned ceremony implementation. The #52 ruling invariants ride exactly these triggers — but the caller above is no longer the #18 shape, so adopting current triggers is a stub edit, not a bare pin bump. `review_requested` and `review_request_removed` on diff --git a/test/labels-triggers.test.sh b/test/labels-triggers.test.sh index f76ed2d..1f5220a 100644 --- a/test/labels-triggers.test.sh +++ b/test/labels-triggers.test.sh @@ -153,35 +153,30 @@ check "pull_request_target keeps the labeled handoff wake" 0 "labeled" \ # ---- fork heads carry a read-only token on this Forgejo (#241) -------------- # Same-repo heads keep the existing immediate scope + sweep-dispatch path. A # fork-headed pull_request_target run must attempt no write: both write-capable -# jobs exclude it, while one successful job explains that the scheduled sweep -# owns its labels. These read the parsed workflow fields rather than grepping -# prose, so a comment cannot satisfy the contract. -job_if_contains_all() { # $1 = file, $2 = job, remaining args = predicates - local file="$1" job="$2" expression predicate - shift 2 - expression="$(yq -r ".jobs.$job.if // \"\"" "$file")" - for predicate in "$@"; do - grep -qF "$predicate" <<<"$expression" || return 1 - done +# jobs exclude it, while one successful job explains exactly what the scheduled +# sweep does and does not supply. Compare the whole normalised expressions: a +# substring guard also accepts a future negation that inverts the gate. +job_if_expression() { # $1 = file, $2 = job + yq -r ".jobs.$2.if // \"\"" "$1" | + tr '\n' ' ' | + awk '{$1=$1; print}' } -check "scope writes only for a same-repo PR head" 0 "" \ - job_if_contains_all "$REUSABLE" scope \ - "github.event.pull_request.head.repo.full_name == github.repository" -check "the sweep trigger preserves non-PR events and excludes fork heads" 0 "" \ - job_if_contains_all "$REUSABLE" trigger \ - "github.event_name != 'pull_request_target'" \ - "github.event.pull_request.head.repo.full_name == github.repository" -check "a fork-headed PR selects the successful explanation job" 0 "" \ - job_if_contains_all "$REUSABLE" fork_head \ - "github.event_name == 'pull_request_target'" \ - "github.event.pull_request.head.repo.full_name != github.repository" +check "scope writes only for a same-repo PR head" 0 \ + "github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name == github.repository && github.event.action != 'labeled' && github.event.action != 'unlabeled' && github.event.action != 'review_requested' && github.event.action != 'review_request_removed'" \ + job_if_expression "$REUSABLE" scope +check "the sweep trigger preserves non-PR events and excludes fork heads" 0 \ + "github.event_name != 'pull_request_target' || github.event.pull_request.head.repo.full_name == github.repository" \ + job_if_expression "$REUSABLE" trigger +check "a fork-headed PR selects the successful explanation job" 0 \ + "github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name != github.repository" \ + job_if_expression "$REUSABLE" fork_head fork_head_step() { yq -r '.jobs.fork_head.steps[] | select(.name == "explain deferred fork labels") | .run' \ "$REUSABLE" | bash } -check "the fork path names its read-only token and sweep-cadence wake" 0 \ - "read-only token; writes deferred to the scheduled sweep cadence" \ +check "the fork path distinguishes swept state from unsupported scope writes" 0 \ + "read-only token; state, blocker, and handoff reconciliation deferred to the scheduled sweep; path-derived scope labels are not applied to fork heads" \ fork_head_step summary