Skip to content

Commit 72d9fd5

Browse files
luisleo526claude
andauthored
ci(release): narrow release-bump exemption in the release gate (CR-245, G13, v2) (#486)
* ci(release): accept a release-bump commit on main when the release App pushed it (CR-245, round 1) The release workflow pushes a version-bump commit to main; no PR head has that tree, so the next release run refused at phase 1. The gate now also accepts main's head when it is a bump commit that (a) every push-event run of the sha on main records as pushed by the release App (actor and triggering_actor both pineforge-app[bot], at least one run, all pages read, a run by any other actor refuses), (b) has a single parent that itself passes phase 1 (a bump on a bump or a merge commit refuses), and (c) touches exactly the files the workflow writes and stages, VERSION and docker/run_failure_codes_diff.json, as modifications with unchanged mode 100644 and nothing else. Red-first tests through gate() with the injected API for the accepted path and each refusal, a mutation control per condition, preflight pins and docs. Commit metadata is not used for identity: it is forgeable. Round 2 adds the branch-ruleset check that makes the App the only possible pusher. Lane: ci-fu-cr245b (Codex gpt-6.1-sol). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * ci(release): the bump exemption also requires that only the release App can push to main (CR-245, round 2) The actor check of round 1 is only as strong as the guarantee that nobody else can produce a push run as the release App. The gate now reads the repository's branch rulesets at gate time and requires that the cumulative bypass of every ACTIVE ruleset that applies to main and carries a pull_request or required_status_checks rule is exactly the release App (Integration 4105147, bypass mode always). It refuses when no push-blocking ruleset applies to main, when one is disabled or evaluate-only, when another actor or a pull-request-only bypass appears, when bypass_actors is not returned, when an inventory or detail response is malformed or incomplete (every page is read and linked), when an applicable ref pattern is not understood, and on any API error. No ruleset id or name is hard-coded. The gate relies on the App installation permission `administration: read`; release.yml, docs/ci.md and the preflight pins say so, so removing the permission is a visible breaking change. Nineteen ruleset tests and thirteen source mutation controls; preflight workflow mutations for the gate token wiring. Rounds 1 and 2 land together. Lane: ci-fu-cr245c (Codex gpt-6.1-sol). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * ci(release): the bump exemption needs one active pull_request ruleset restricted to the release App; Actions pagination honours Link (CR-245, round 3) Replaces the round-2 barrier of a8b1276 ("the bump exemption also requires that only the release App can push to main"): it removes the round-2 bypass-intersection sentences and the status-only acceptance that a8b1276 added to docs/ci.md, and rewrites its tests. Fresh sol read of the round-2 head: intersecting bypass descriptors across rulesets does not prove an App-only barrier (a person who holds a role and a team bypasses two rulesets whose lists share only the App entry), and a required_status_checks rule alone is not a push barrier. The condition is now: at least one ACTIVE branch ruleset applies to main, carries a pull_request rule, and its OWN bypass list is exactly the release App (Integration 4105147, bypass mode always); other rulesets, such as the broad default one, no longer matter. required_status_checks no longer counts. The Actions workflow-runs reader also proves completeness with the Link header (an advertised unread next page refuses), as the rulesets reader already did. The round-2 tests that encoded the intersection and the status-only acceptance are rewritten (status-only now refuses) and new red rows cover overlapping role/team principals, a hybrid PR/status pair, a valid barrier beside broader rulesets, a second bypass actor, a non-always mode and the unread-page input; docs, preflight pins and the release.yml comment follow the new wording. Two refusal-text expectations in test_ci_release_gate.py were wrong, not the gate: the pagination row lacked "returned" and the empty-payload row doubled it. Both now assert the text the gate emits. A second fresh sol read found that the HTTP page check and the JSON page check counted different populations: one HTTP body could carry several JSON documents, so a valid page followed by a headerless document still returned the green bump verdict (for the runs reader and the rulesets reader alike). Each framed HTTP body must now be exactly one JSON document, checked before the pages are joined and before the Link relations are trusted; extra or trailing data, an empty body and a partially headerless response refuse with the endpoint named. New red rows cover the runs example, the rulesets analogue, an extra document on page 2, trailing garbage, partially missing headers, an empty body with a next Link and the PR/status bodies; two new full-source mutants remove the check and must go green on the mutant only. Lane: ci-fu-cr245d, ci-fu-cr245e and ci-fu-cr245f (Codex gpt-6.1-sol). Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent b7bea58 commit 72d9fd5

6 files changed

Lines changed: 1478 additions & 21 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,9 @@ jobs:
8989
# Org GitHub App token (no PAT — never expires). Authorizes the version
9090
# bump commit/tag push to protected main (the App is a bypass actor on the
9191
# org ruleset) AND the downstream hub dispatch. Scoped to this repo + the
92-
# hub. Minted first so checkout can push with it.
92+
# hub. Minted first so checkout can push with it. GitHub records this
93+
# authenticated pusher as pineforge-app[bot] on exact-main push runs;
94+
# ci_release_gate.py pins that login for the one-bump phase-1 exemption.
9395
- name: Mint org App token
9496
id: app
9597
uses: actions/create-github-app-token@v1
@@ -111,6 +113,14 @@ jobs:
111113
git config user.name "github-actions[bot]"
112114
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
113115
116+
# Phase 1 also accepts an App-pushed two-file bump on a gated PR merge.
117+
# No matching post-merge push run yet: refuse; retry after it exists.
118+
# The gate requires one active main pull_request ruleset whose own
119+
# bypass_actors is exactly Integration 4105147 with bypass_mode always.
120+
# Other rulesets' bypass lists do not supply or invalidate that barrier.
121+
# Its App permission administration: read exposes bypass_actors; removing
122+
# that permission makes the release-bump exemption refuse every release.
123+
# The workflow-level contents: write scope belongs to GITHUB_TOKEN.
114124
- name: Refuse unless pineforge/verify and pineforge/parity are green
115125
id: gate
116126
env:
@@ -194,7 +204,8 @@ jobs:
194204
# from now on (--check: the diff starts at the newest tag HEAD reaches)
195205
# must pass on the tagged commit before anything is pushed. The commit
196206
# and the tag go up in one atomic push: both land or neither does, so
197-
# main never holds a diff reset to a tag the remote lacks.
207+
# main never holds a diff reset to a tag the remote lacks. Keep these
208+
# exact two modified regular files: the release gate exempts no others.
198209
#
199210
# When a step fails after this push (gh release create, say), the tag
200211
# exists and re-running this run stops at "Compute next version" (tag

‎docs/ci.md‎

Lines changed: 83 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1286,8 +1286,88 @@ exactly one associated merged PR targeting `main`, with `merge_commit_sha`
12861286
equal to the release sha and a head tree matching the released tree, then
12871287
reads that head's full contexts through the statuses API. PRs targeting other
12881288
bases or naming a different merge commit are ignored; malformed fields refuse.
1289-
Zero matches refuse; multiple matches refuse and name every matching PR, with
1290-
no preference for the newest.
1289+
When qualifying merged PRs exist, zero tree matches refuse; multiple matches
1290+
refuse and name every matching PR, with no preference for the newest. A failed
1291+
tree or status check never falls back to a release bump.
1292+
1293+
When there is no qualifying merged PR for the current main sha, phase 1 permits
1294+
one release bump only when all three conditions hold:
1295+
1296+
1. GitHub's `repos/{repo}/actions/runs?head_sha=<sha>&per_page=100` returns at
1297+
least one run with `event == "push"`, `head_branch == "main"` and
1298+
`head_sha == <sha>`. Every such run must have both `actor.login` and
1299+
`triggering_actor.login` equal to the gate's fixed `RELEASE_PUSH_ACTOR`,
1300+
`pineforge-app[bot]`, the release App installation token used by
1301+
`release.yml`. All pages are read; missing HTTP headers, malformed pages,
1302+
an advertised unread Link next page, changing `total_count` or a row count
1303+
different from that total refuse. A matching count never overrides an
1304+
unread next page. Reaching the filtered API's 1000-run limit also refuses,
1305+
because completeness at that boundary cannot be inferred. Zero matching
1306+
runs refuse. A bump pushed seconds
1307+
ago may not have a post-merge run yet; retry the release once that push run exists.
1308+
At gate time, the guard also reads `repos/{repo}` to confirm main is still
1309+
the default branch, lists `repos/{repo}/rulesets?includes_parents=true&per_page=100`
1310+
with every page, and reads each branch ruleset by id for its conditions,
1311+
rules and `bypass_actors`. It selects branch rulesets whose `ref_name`
1312+
includes main (`~DEFAULT_BRANCH`, `refs/heads/main`, `~ALL`, or a matching
1313+
pathname pattern) without excluding main. Simple `*` and `?` patterns do
1314+
not cross `/`; advanced or unknown pattern syntax refuses.
1315+
There must be **one active applicable branch ruleset** carrying a
1316+
`pull_request` rule whose **own** `bypass_actors` list is exactly
1317+
`[{"actor_type": "Integration", "actor_id": 4105147, "bypass_mode": "always"}]`,
1318+
the release App token used by `release.yml`. That ruleset's PR rule blocks
1319+
every direct push by an actor that cannot bypass that same ruleset.
1320+
A status-check-only rule permits writers to push when its checks pass
1321+
and supplies no barrier. A disabled, evaluating or main-excluded App-only
1322+
PR ruleset supplies no barrier either. A second bypass actor, a different
1323+
App/type or a PR-only bypass mode on the candidate disqualifies it.
1324+
Other rulesets' bypass lists and enforcement do not supply or invalidate
1325+
a valid App-only PR barrier. Lists are never intersected: a person may hold
1326+
a repository role and belong to a team represented by different descriptors.
1327+
Ruleset names and ids are not pinned; tag-creation rulesets provide no
1328+
evidence about pushes to main. Every branch detail is still validated,
1329+
including details after a valid barrier, so unreadable or malformed
1330+
evidence refuses.
1331+
Both Actions and ruleset list reads retain HTTP Link headers and check
1332+
every advertised next page, consecutive page numbers and a terminal page;
1333+
missing headers, incomplete pagination, API errors, inconsistent
1334+
list/detail fields and malformed payloads refuse.
1335+
Every HTTP response body read as JSON, including paginated PR and status
1336+
lists, must contain exactly one JSON document before pagination is checked.
1337+
Extra documents (including a later page without its HTTP headers) or
1338+
trailing garbage refuse with an endpoint-specific diagnostic:
1339+
`returned an HTTP response body with trailing data; expected exactly one JSON document`.
1340+
Empty bodies refuse with `returned an empty payload`; a valid empty JSON
1341+
array is still a complete document.
1342+
2. The bump has exactly one parent, and that parent passes the ordinary
1343+
phase-1 merged-PR/tree/full-status checks above, including the allowed
1344+
status creator. This depth is exactly one: a bump on another bump refuses
1345+
even when its grandparent was gated. A merge commit also refuses.
1346+
3. The complete parent-to-bump file diff is exactly `VERSION` and
1347+
`docker/run_failure_codes_diff.json`, both status `M`, both regular blobs
1348+
with mode `100644` before and after. The gate compares complete recursive
1349+
Git trees, derives `M` from an existing path with a changed blob, and
1350+
refuses truncated trees. Added, deleted or renamed files, mode changes,
1351+
any extra file (including README or CHANGELOG), either missing
1352+
modification, and an empty diff refuse.
1353+
1354+
Condition 1 proves who pushed this sha to main. It does not prove that the
1355+
pushed content is what a particular release run built, or exclusive use of
1356+
the App credential by this workflow. Commit author, committer and verification
1357+
metadata provide no push-identity evidence. Condition 3 bounds the content
1358+
changes to the two files whose values the release workflow computes: the next
1359+
version and the reset catalog diff. Preflight pins the exact writer, staging,
1360+
commit and atomic-push step and the App-token checkout wiring.
1361+
1362+
The gate relies on the release App permission `administration: read` to read
1363+
`bypass_actors`. The App installation has that permission and `contents: write`;
1364+
the workflow-level `contents: write` setting scopes GITHUB_TOKEN and does not
1365+
grant App permissions. Tokens without administration access may receive a
1366+
ruleset response with `bypass_actors` omitted; a missing field refuses, and
1367+
the guard never assumes an unreadable list is empty or App-only.
1368+
Removing this App permission makes every release-bump exemption refuse.
1369+
Preflight pins the unconditional gate invocation and its App token, and its
1370+
binding release-gate tests pin this permission dependency in code and docs.
12911371

12921372
Phase 2 is **not live yet**: `MAIN_PROOF_WATCHER_FIRST_SHA` in
12931373
`scripts/ci_release_gate.py` is `None`. When C2 main-watch (#176) supplies the
@@ -1296,7 +1376,7 @@ fixed in that constant by a reviewed PR. The release job cannot configure it
12961376
through an environment variable or workflow input. At that sha and every
12971377
descendant, the guard requires a main-proof receipt for the **exact main
12981378
sha** with both full contexts green and does not consult PR heads. Missing,
1299-
unreadable or non-green receipts refuse, with no transitional fallback.
1379+
unreadable or non-green receipts refuse, with no PR or release-bump fallback.
13001380
Commits preceding the cut-over retain phase 1; unknown ancestry refuses.
13011381
The reader seam defines normalized context states, not a receipt storage format.
13021382

‎scripts/ci_preflight.py‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1125,6 +1125,73 @@ def _step_block(step: str, key: str) -> list[str]:
11251125
return _job_block(re.sub(r'^( *)- ', r'\1 ', step, count=1), key)
11261126

11271127

1128+
# ci_release_gate.py's phase-1 exemption is bounded by this exact writer.
1129+
RELEASE_BUMP_PUBLISH_STEP = r''' - name: Write bumped VERSION, commit, tag, push
1130+
id: publish
1131+
if: ${{ !inputs.dry_run }}
1132+
env:
1133+
NEXT: ${{ steps.bump.outputs.next }}
1134+
TAG: ${{ steps.bump.outputs.tag }}
1135+
RESET: ${{ steps.catalog.outputs.reset }}
1136+
run: |
1137+
set -euo pipefail
1138+
printf '%s\n' "${NEXT}" > VERSION
1139+
cp "${RESET}" docker/run_failure_codes_diff.json
1140+
git add VERSION docker/run_failure_codes_diff.json
1141+
git commit -m "chore(release): ${TAG}"
1142+
git tag -a "${TAG}" -m "Release ${TAG}"
1143+
python3 scripts/gen_run_failure_catalog_diff.py --check
1144+
git push --atomic origin HEAD "${TAG}"
1145+
echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
1146+
'''
1147+
1148+
# This App installation has administration: read, which exposes bypass_actors.
1149+
# The gate requires one active main pull_request ruleset whose own bypass list
1150+
# is exactly Integration 4105147 with bypass_mode always.
1151+
# The workflow's contents: write GITHUB_TOKEN cannot replace that credential.
1152+
RELEASE_GATE_STEP = r''' - name: Refuse unless pineforge/verify and pineforge/parity are green
1153+
id: gate
1154+
env:
1155+
GH_TOKEN: ${{ steps.app.outputs.token }}
1156+
GITHUB_REPOSITORY: ${{ github.repository }}
1157+
GITHUB_SHA: ${{ github.sha }}
1158+
GITHUB_REF: ${{ github.ref }}
1159+
run: |
1160+
python3 scripts/ci_release_gate.py gate \
1161+
--repo "${GITHUB_REPOSITORY}" --sha "${GITHUB_SHA}" --ref "${GITHUB_REF}"
1162+
'''
1163+
1164+
1165+
def release_bump_workflow_findings(workflow: str) -> list[str]:
1166+
steps = _steps(_jobs(workflow).get('release', ''))
1167+
publish = _step_named(steps, ' - name: Write bumped VERSION, commit, tag, push')
1168+
findings = []
1169+
if _code(publish) != _code(RELEASE_BUMP_PUBLISH_STEP):
1170+
findings.append('release.yml must keep the exact two-file release bump writer, '
1171+
'commit and atomic push')
1172+
gate = _step_named(steps, ' - name: Refuse unless pineforge/verify and pineforge/parity are green')
1173+
if _code(gate) != _code(RELEASE_GATE_STEP):
1174+
findings.append('release.yml must keep the unconditional release gate '
1175+
'with its administration-readable App token '
1176+
'for the App-only main pull_request barrier')
1177+
app = _step_named(steps, ' - name: Mint org App token')
1178+
checkout = _step_named(steps, ' - name: Checkout (full history)')
1179+
if (_step_values(app, 'id') != ['app']
1180+
or _step_values(app, 'uses') != ['actions/create-github-app-token@v1']
1181+
or _step_block(app, 'with') != [
1182+
' with:',
1183+
' app-id: ${{ secrets.PINEFORGE_APP_ID }}',
1184+
' private-key: ${{ secrets.PINEFORGE_APP_PRIVATE_KEY }}',
1185+
' owner: ${{ github.repository_owner }}',
1186+
' repositories: pineforge-engine']
1187+
or _step_values(checkout, 'uses') != ['actions/checkout@v4']
1188+
or _step_block(checkout, 'with') != [
1189+
' with:', ' fetch-depth: 0',
1190+
' token: ${{ steps.app.outputs.token }}']):
1191+
findings.append('release.yml bump push must use the release App installation token')
1192+
return findings
1193+
1194+
11281195
def fast_rows(cmake: str) -> list[str]:
11291196
"""Read the single CMake population; no duplicate Python list of rows."""
11301197
blocks = re.findall(r'^set\(PINEFORGE_PR_FAST_TESTS\n(.*?)^\)', cmake,
@@ -1554,6 +1621,8 @@ def ci_workflow_findings(ci: str, native: str, promote: str, cmake: str,
15541621
or _job_values(_jobs(subset).get('corpus-parity-subset', ''), 'if')):
15551622
findings.append('PR parity workflow must retain only workflow_call, authz and an unconditional subset job')
15561623
findings += docs_workflow_findings(docs, docs_post)
1624+
if 'release.yml' in workflows:
1625+
findings += release_bump_workflow_findings(workflows['release.yml'])
15571626
for name, workflow in workflows.items():
15581627
if name in RELEASE_JOB_RUNNERS:
15591628
continue
@@ -1895,6 +1964,9 @@ def check_commands(source: Path, output: Path | None = None,
18951964
[sys.executable, str(source / 'scripts/test_report_outputs_keys.py')]),
18961965
('release-version-tests',
18971966
[sys.executable, str(source / 'scripts/test_release_version.py')]),
1967+
# Includes the single App-only main pull_request barrier, complete
1968+
# Actions/ruleset pages, permission docs, bump identity/parent/tree diff.
1969+
# Binding in both fast/all.
18981970
('release-gate-tests', [sys.executable, str(source / 'scripts/test_ci_release_gate.py')]),
18991971
# R5 run-failure codes: the catalog diff release.yml stamps is a tested
19001972
# script, and the code tables of docs/pages/run-failure-codes.md are

0 commit comments

Comments
 (0)