Skip to content

Commit a8b1276

Browse files
luisleo526claude
andcommitted
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]>
1 parent e726ad9 commit a8b1276

6 files changed

Lines changed: 576 additions & 4 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,10 @@ jobs:
115115
116116
# Phase 1 also accepts an App-pushed two-file bump on a gated PR merge.
117117
# No matching post-merge push run yet: refuse; retry after it exists.
118+
# The gate reads main's cumulative branch rulesets with this App token.
119+
# Its App permission administration: read exposes bypass_actors; removing
120+
# that permission makes the release-bump exemption refuse every release.
121+
# The workflow-level contents: write scope belongs to GITHUB_TOKEN.
118122
- name: Refuse unless pineforge/verify and pineforge/parity are green
119123
id: gate
120124
env:

‎docs/ci.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1303,6 +1303,27 @@ one release bump only when all three conditions hold:
13031303
filtered API's 1000-run limit also refuses, because completeness at that
13041304
boundary cannot be inferred. Zero matching runs refuse. A bump pushed seconds
13051305
ago may not have a post-merge run yet; retry the release once that push run exists.
1306+
At gate time, the guard also reads `repos/{repo}` to confirm main is still
1307+
the default branch, lists `repos/{repo}/rulesets?includes_parents=true&per_page=100`
1308+
with every page, and reads each branch ruleset by id for its conditions,
1309+
rules and `bypass_actors`. It selects branch rulesets whose `ref_name`
1310+
includes main (`~DEFAULT_BRANCH`, `refs/heads/main`, `~ALL`, or a matching
1311+
pathname pattern) without excluding main. Simple `*` and `?` patterns do
1312+
not cross `/`; advanced or unknown pattern syntax refuses.
1313+
There must be at least one applicable `pull_request` or
1314+
`required_status_checks` rule. Every applicable ruleset carrying either
1315+
push-blocking rule must be `active`; disabled or evaluate enforcement refuses.
1316+
Their bypass-list **intersection**, including actor type, id and mode,
1317+
must be exactly Integration `4105147` with `bypass_mode == "always"`,
1318+
the release App token used by `release.yml`. Another shared actor, a
1319+
PR-only App bypass, an empty intersection, or no blocking ruleset refuses.
1320+
Broader bypass lists on another cumulative ruleset do not grant access
1321+
through an App-only restriction. Ruleset names and ids are not pinned;
1322+
tag-creation rulesets provide no evidence about pushes to main.
1323+
The list read retains HTTP Link headers and checks every advertised next
1324+
page, consecutive page numbers and a terminal page; missing headers,
1325+
incomplete pagination, API errors, inconsistent list/detail fields and
1326+
malformed payloads refuse.
13061327
2. The bump has exactly one parent, and that parent passes the ordinary
13071328
phase-1 merged-PR/tree/full-status checks above, including the allowed
13081329
status creator. This depth is exactly one: a bump on another bump refuses
@@ -1323,6 +1344,16 @@ changes to the two files whose values the release workflow computes: the next
13231344
version and the reset catalog diff. Preflight pins the exact writer, staging,
13241345
commit and atomic-push step and the App-token checkout wiring.
13251346

1347+
The gate relies on the release App permission `administration: read` to read
1348+
`bypass_actors`. The App installation has that permission and `contents: write`;
1349+
the workflow-level `contents: write` setting scopes GITHUB_TOKEN and does not
1350+
grant App permissions. Tokens without administration access may receive a
1351+
ruleset response with `bypass_actors` omitted; a missing field refuses, and
1352+
the guard never assumes an unreadable list is empty or App-only.
1353+
Removing this App permission makes every release-bump exemption refuse.
1354+
Preflight pins the unconditional gate invocation and its App token, and its
1355+
binding release-gate tests pin this permission dependency in code and docs.
1356+
13261357
Phase 2 is **not live yet**: `MAIN_PROOF_WATCHER_FIRST_SHA` in
13271358
`scripts/ci_release_gate.py` is `None`. When C2 main-watch (#176) supplies the
13281359
receipt reader, the cut-over is the watcher's **first recorded main sha**,

‎scripts/ci_preflight.py‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1135,6 +1135,20 @@ def _step_block(step: str, key: str) -> list[str]:
11351135
echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
11361136
'''
11371137

1138+
# This App installation has administration: read, which exposes bypass_actors.
1139+
# The workflow's contents: write GITHUB_TOKEN cannot replace that credential.
1140+
RELEASE_GATE_STEP = r''' - name: Refuse unless pineforge/verify and pineforge/parity are green
1141+
id: gate
1142+
env:
1143+
GH_TOKEN: ${{ steps.app.outputs.token }}
1144+
GITHUB_REPOSITORY: ${{ github.repository }}
1145+
GITHUB_SHA: ${{ github.sha }}
1146+
GITHUB_REF: ${{ github.ref }}
1147+
run: |
1148+
python3 scripts/ci_release_gate.py gate \
1149+
--repo "${GITHUB_REPOSITORY}" --sha "${GITHUB_SHA}" --ref "${GITHUB_REF}"
1150+
'''
1151+
11381152

11391153
def release_bump_workflow_findings(workflow: str) -> list[str]:
11401154
steps = _steps(_jobs(workflow).get('release', ''))
@@ -1143,6 +1157,10 @@ def release_bump_workflow_findings(workflow: str) -> list[str]:
11431157
if _code(publish) != _code(RELEASE_BUMP_PUBLISH_STEP):
11441158
findings.append('release.yml must keep the exact two-file release bump writer, '
11451159
'commit and atomic push')
1160+
gate = _step_named(steps, ' - name: Refuse unless pineforge/verify and pineforge/parity are green')
1161+
if _code(gate) != _code(RELEASE_GATE_STEP):
1162+
findings.append('release.yml must keep the unconditional release gate '
1163+
'with its administration-readable App token')
11461164
app = _step_named(steps, ' - name: Mint org App token')
11471165
checkout = _step_named(steps, ' - name: Checkout (full history)')
11481166
if (_step_values(app, 'id') != ['app']
@@ -1926,7 +1944,8 @@ def check_commands(source: Path, output: Path | None = None,
19261944
[sys.executable, str(source / 'scripts/test_report_outputs_keys.py')]),
19271945
('release-version-tests',
19281946
[sys.executable, str(source / 'scripts/test_release_version.py')]),
1929-
# Includes authenticated bump identity, gated parent and exact tree diff.
1947+
# Includes App-only main rulesets, permission docs, authenticated bump
1948+
# identity, gated parent and exact tree diff; binding in both fast/all.
19301949
('release-gate-tests', [sys.executable, str(source / 'scripts/test_ci_release_gate.py')]),
19311950
# R5 run-failure codes: the catalog diff release.yml stamps is a tested
19321951
# script, and the code tables of docs/pages/run-failure-codes.md are

‎scripts/ci_release_gate.py‎

Lines changed: 147 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import subprocess
2020
import sys
2121
from typing import Callable
22+
from urllib.parse import parse_qs, urlsplit
2223

2324

2425
CONTEXTS = ("pineforge/verify", "pineforge/parity")
@@ -27,6 +28,10 @@
2728
# release.yml pushes protected main with its PINEFORGE_APP_ID installation token.
2829
# This is GitHub's authenticated push actor, never the commit's author/committer.
2930
RELEASE_PUSH_ACTOR = "pineforge-app[bot]"
31+
# Integration for release.yml's PINEFORGE_APP_ID installation token.
32+
# The gate relies on App permission administration: read to see bypass_actors;
33+
# removing it makes every release-bump exemption refuse, even with contents: write.
34+
RELEASE_APP_ID = 4105147
3035
RELEASE_BUMP_PATHS = frozenset(("VERSION", "docker/run_failure_codes_diff.json"))
3136
MAIN_PROOF_WATCHER_FIRST_SHA: str | None = None
3237
"""None = the watcher is not live yet. Otherwise its FIRST recorded main sha.
@@ -75,7 +80,8 @@ def _http_failure(raw: str, *, exception: bool = False) -> str | None:
7580
return None
7681

7782

78-
def _read_text(api: API, endpoint: str, **options) -> str:
83+
def _read_text(api: API, endpoint: str, *, complete_rulesets: bool = False,
84+
**options) -> str:
7985
try:
8086
raw = api(endpoint, **options)
8187
except subprocess.CalledProcessError as exc:
@@ -94,6 +100,36 @@ def _read_text(api: API, endpoint: str, **options) -> str:
94100
# --include emits one header block per page, also when --jq is used.
95101
# Preserve page boundaries so a good page cannot hide an empty response.
96102
responses = list(_HTTP_RESPONSE.finditer(raw))
103+
if complete_rulesets:
104+
# Unlike Actions, the ruleset list has no total_count. Keep gh's HTTP
105+
# Link evidence until we prove every advertised next page was read.
106+
failure = f"API {endpoint} returned incomplete ruleset pagination"
107+
if not responses or not options.get("paginate"):
108+
raise ReleaseGateError(f"{failure}: missing HTTP page headers")
109+
for index, response in enumerate(responses):
110+
links = re.findall(r"^Link:[ \t]*([^\r\n]*)", response[0],
111+
re.MULTILINE | re.IGNORECASE)
112+
relations = {}
113+
for field in links:
114+
for link in field.split(","):
115+
parsed = re.fullmatch(
116+
r'\s*<(https://[^<>\s]+)>;\s*rel="(next|prev|first|last)"\s*', link)
117+
if parsed is None or parsed[2] in relations:
118+
raise ReleaseGateError(f"{failure}: malformed Link header")
119+
try:
120+
page = parse_qs(urlsplit(parsed[1]).query).get("page")
121+
except ValueError as exc:
122+
raise ReleaseGateError(f"{failure}: invalid page URL") from exc
123+
if (page is None or len(page) != 1
124+
or re.fullmatch(r"[1-9][0-9]*", page[0]) is None):
125+
raise ReleaseGateError(f"{failure}: invalid page number")
126+
relations[parsed[2]] = int(page[0])
127+
if ("next" in relations) != (index + 1 < len(responses)):
128+
raise ReleaseGateError(f"{failure}: unread or unlinked next page")
129+
expected = {"next": index + 2, "prev": index,
130+
"first": 1, "last": len(responses)}
131+
if any(page != expected[relation] for relation, page in relations.items()):
132+
raise ReleaseGateError(f"{failure}: skipped, repeated or truncated pages")
97133
if responses:
98134
if raw[:responses[0].start()].strip() or (
99135
not options.get("paginate", False) and len(responses) != 1):
@@ -112,8 +148,8 @@ def _read_text(api: API, endpoint: str, **options) -> str:
112148

113149

114150
def _read_json(api: API, endpoint: str, *, paginate: bool = False,
115-
items_key: str | None = None):
116-
raw = _read_text(api, endpoint, paginate=paginate)
151+
items_key: str | None = None, complete_rulesets: bool = False):
152+
raw = _read_text(api, endpoint, paginate=paginate, complete_rulesets=complete_rulesets)
117153
try:
118154
if not paginate:
119155
result = json.loads(raw)
@@ -246,6 +282,113 @@ def _require_release_push(api: API, repo: str, sha: str) -> None:
246282
raise ReleaseGateError(f"no exact-main push workflow run for release bump {sha}")
247283

248284

285+
def _ruleset_applies_to_main(payload: dict, endpoint: str) -> bool:
286+
conditions = payload.get("conditions")
287+
refs = conditions.get("ref_name") if isinstance(conditions, dict) else None
288+
if (not isinstance(refs, dict)
289+
or any(not isinstance(refs.get(key), list)
290+
or any(not isinstance(pattern, str) or not pattern
291+
for pattern in refs[key]) for key in ("include", "exclude"))):
292+
raise ReleaseGateError(f"API {endpoint} returned invalid ref_name conditions")
293+
294+
def matches(pattern: str) -> bool:
295+
if pattern in ("~DEFAULT_BRANCH", "~ALL"):
296+
return True
297+
# GitHub uses pathname-aware fnmatch: * and ? cannot cross '/'.
298+
# Refuse advanced/unknown syntax instead of guessing applicability.
299+
if (pattern.startswith("~") or "**" in pattern
300+
or any(char in pattern for char in ("[", "]", "{", "}", "\\"))):
301+
raise ReleaseGateError(f"API {endpoint} returned invalid ref_name conditions: "
302+
f"unsupported pattern {pattern!r}")
303+
expression = re.escape(pattern).replace(r"\*", "[^/]*").replace(r"\?", "[^/]")
304+
return re.fullmatch(expression, "refs/heads/main") is not None
305+
306+
included = [matches(pattern) for pattern in refs["include"]]
307+
excluded = [matches(pattern) for pattern in refs["exclude"]]
308+
return any(included) and not any(excluded)
309+
310+
311+
def _ruleset_bypasses(payload: dict, endpoint: str) -> set[tuple[str, int | None, str]]:
312+
actors = payload.get("bypass_actors")
313+
if not isinstance(actors, list):
314+
raise ReleaseGateError(f"API {endpoint} returned missing or invalid bypass_actors "
315+
"(App requires administration: read)")
316+
bypasses = set()
317+
for actor in actors:
318+
if not isinstance(actor, dict):
319+
raise ReleaseGateError(f"API {endpoint} returned invalid bypass actor: {actor!r}")
320+
kind, number, mode = (actor.get(key) for key in
321+
("actor_type", "actor_id", "bypass_mode"))
322+
if (not isinstance(kind, str)
323+
or kind not in ("Integration", "OrganizationAdmin", "DeployKey",
324+
"RepositoryRole", "Team")
325+
or "actor_id" not in actor
326+
or (number is None and kind not in ("OrganizationAdmin", "DeployKey"))
327+
or (number is not None and (type(number) is not int or number <= 0))
328+
or not isinstance(mode, str) or mode not in ("always", "pull_request")):
329+
raise ReleaseGateError(f"API {endpoint} returned invalid bypass actor: {actor!r}")
330+
identity = (kind, number, mode)
331+
if identity in bypasses:
332+
raise ReleaseGateError(f"API {endpoint} returned invalid bypass actor: duplicate")
333+
bypasses.add(identity)
334+
return bypasses
335+
336+
337+
def _require_release_rulesets(api: API, repo: str) -> None:
338+
endpoint = f"repos/{repo}"
339+
repository = _read_json(api, endpoint)
340+
if not isinstance(repository, dict) or repository.get("default_branch") != "main":
341+
raise ReleaseGateError(f"API {endpoint} must identify main as the default branch")
342+
343+
endpoint = f"repos/{repo}/rulesets?includes_parents=true&per_page=100"
344+
inventory = _read_json(api, endpoint, paginate=True, complete_rulesets=True)
345+
seen, summaries = set(), []
346+
for row in inventory:
347+
if (not isinstance(row, dict) or type(row.get("id")) is not int or row["id"] <= 0
348+
or not isinstance(row.get("target"), str)
349+
or row["target"] not in ("branch", "tag", "push")
350+
or not isinstance(row.get("enforcement"), str)
351+
or row["enforcement"] not in ("active", "disabled", "evaluate")):
352+
raise ReleaseGateError(f"API {endpoint} returned invalid ruleset summary: {row!r}")
353+
if row["id"] in seen:
354+
raise ReleaseGateError(f"API {endpoint} returned duplicate ruleset id {row['id']}")
355+
seen.add(row["id"])
356+
summaries.append(row)
357+
358+
intersection = None
359+
for summary in summaries:
360+
if summary["target"] != "branch":
361+
continue
362+
endpoint = f"repos/{repo}/rulesets/{summary['id']}"
363+
payload = _read_json(api, endpoint)
364+
if (not isinstance(payload, dict) or type(payload.get("id")) is not int
365+
or any(payload.get(key) != summary[key]
366+
for key in ("id", "target", "enforcement"))):
367+
raise ReleaseGateError(f"API {endpoint} returned inconsistent ruleset detail")
368+
bypasses = _ruleset_bypasses(payload, endpoint)
369+
applies = _ruleset_applies_to_main(payload, endpoint)
370+
rules = payload.get("rules")
371+
if (not isinstance(rules, list)
372+
or any(not isinstance(rule, dict) or not isinstance(rule.get("type"), str)
373+
or not rule["type"] for rule in rules)):
374+
raise ReleaseGateError(f"API {endpoint} returned invalid rules")
375+
blocking = any(rule["type"] in ("pull_request", "required_status_checks")
376+
for rule in rules)
377+
if not applies or not blocking:
378+
continue
379+
if payload["enforcement"] != "active":
380+
raise ReleaseGateError(
381+
f"main push-blocking ruleset {summary['id']} must be active")
382+
# Rulesets are cumulative: an actor must bypass EVERY main push blocker.
383+
intersection = bypasses if intersection is None else intersection & bypasses
384+
385+
if intersection is None:
386+
raise ReleaseGateError("main has no active applicable push-blocking ruleset")
387+
if intersection != {("Integration", RELEASE_APP_ID, "always")}:
388+
raise ReleaseGateError("main direct-push bypass intersection must be exactly "
389+
f"Integration {RELEASE_APP_ID} with bypass_mode always")
390+
391+
249392
def _tree_files(api: API, repo: str, tree: str) -> dict[str, tuple[str, str, str]]:
250393
endpoint = f"repos/{repo}/git/trees/{tree}?recursive=1"
251394
payload = _read_json(api, endpoint)
@@ -275,6 +418,7 @@ def _tree_files(api: API, repo: str, tree: str) -> dict[str, tuple[str, str, str
275418

276419
def _release_bump(api: API, repo: str, sha: str) -> str:
277420
_require_release_push(api, repo, sha)
421+
_require_release_rulesets(api, repo)
278422
candidate = _commit_info(api, repo, sha)
279423
parents = candidate.get("parents")
280424
if (not isinstance(parents, list) or len(parents) != 1

‎scripts/test_ci_preflight.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3416,6 +3416,24 @@ def test_release_bump_app_token_mutations_refuse(self):
34163416
ci_workflow_findings(
34173417
*original, others={**others, 'release.yml': changed}))
34183418

3419+
def test_release_ruleset_reader_token_and_invocation_mutations_refuse(self):
3420+
original, others = self.ci_sources(), self.other_sources()
3421+
release = others['release.yml']
3422+
gate_name = 'Refuse unless pineforge/verify and pineforge/parity are green'
3423+
for before, after in (
3424+
('GH_TOKEN: ${{ steps.app.outputs.token }}', 'GH_TOKEN: ${{ github.token }}'),
3425+
(' id: gate', ' id: gate\n if: inputs.dry_run'),
3426+
('python3 scripts/ci_release_gate.py gate', 'echo release gate green'),
3427+
('--ref "${GITHUB_REF}"', '--ref "${GITHUB_REF}" || true'),
3428+
(' run: |', ' continue-on-error: true\n run: |')):
3429+
with self.subTest(after=after):
3430+
changed = in_step(release, 'release', gate_name, before, after)
3431+
self.assertNotEqual(changed, release)
3432+
self.assertIn('release.yml must keep the unconditional release gate '
3433+
'with its administration-readable App token',
3434+
ci_workflow_findings(
3435+
*original, others={**others, 'release.yml': changed}))
3436+
34193437
def test_no_stage_is_advisory_today(self):
34203438
for entry in check_commands(Path('/src')):
34213439
self.assertFalse(len(entry) > 2 and entry[2], entry[0])

0 commit comments

Comments
 (0)