Skip to content

Commit b5db421

Browse files
committed
ci(release): refuse ambiguous PRs, harden API reads, require full contexts, fix proof cut-over
Round 2 of the release guard. Doc deletion, named as the doc-revert gate asks (introducing commit 3cca5e9): the round-1 line "A release is refused unless the released tree's merged-PR head carries pineforge/verify and pineforge/parity success, read through the statuses API (fail closed); main commits carry no statuses." is deleted and replaced by the "Release guard phases" section: phase 1 keeps the merged-PR-head transition path (one tree-matching PR, several refuse), phase 2 requires the main-proof receipt for the exact main sha at and after the fixed cut-over and never falls back to a PR head.
1 parent 3cca5e9 commit b5db421

3 files changed

Lines changed: 485 additions & 38 deletions

File tree

‎docs/ci.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1061,7 +1061,6 @@ fallback. The `prebuilt` matrix keeps its three legs and
10611061
`runs-on: ${{ matrix.runner }}`; `linux-aarch64` retains `ubuntu-22.04-arm`
10621062
as an existing hosted exception, while `macos-universal` retains
10631063
`macos-latest`. The workflow remains `workflow_dispatch` only.
1064-
A release is refused unless the released tree's merged-PR head carries `pineforge/verify` and `pineforge/parity` success, read through the statuses API (fail closed); main commits carry no statuses.
10651064

10661065
The GCP fleet also routes baseline `promote` in `promote-baseline.yml`
10671066
to `["self-hosted","pf-gcp-main"]`, preserving L6's 15:40 addendum's
@@ -1252,3 +1251,28 @@ split. Cancelled/failed jobs did skip the old compiler post-save, which reduced
12521251
cache freshness; the new save ordering addresses that independently. The
12531252
historical ASan startup assertion remains a separate diagnosis, and splitting
12541253
jobs does not establish a runtime fix or dismiss a sanitizer failure.
1254+
1255+
### Release guard phases
1256+
1257+
The release guard requires exactly `pineforge/verify` and `pineforge/parity`
1258+
to be `success`; lite variants never satisfy either requirement. Phase 1 is
1259+
the **transitional** merged-PR-head path for main commits that predate the
1260+
main watcher. It requires exactly one associated merged PR whose head tree
1261+
matches the released tree, then reads that head's full contexts through the
1262+
statuses API. Zero matches refuse; multiple matches refuse and name every
1263+
matching PR, with no preference for the newest.
1264+
1265+
Phase 2 is **not live yet**: `MAIN_PROOF_WATCHER_FIRST_SHA` in
1266+
`scripts/release_gate.py` is `None`. When C2 main-watch (#176) supplies the
1267+
receipt reader, the cut-over is the watcher's **first recorded main sha**,
1268+
fixed in that constant by a reviewed PR. The release job cannot configure it
1269+
through an environment variable or workflow input. At that sha and every
1270+
descendant, the guard requires a main-proof receipt for the **exact main
1271+
sha** with both full contexts green and does not consult PR heads. Missing,
1272+
unreadable or non-green receipts refuse, with no transitional fallback.
1273+
Commits preceding the cut-over retain phase 1; unknown ancestry refuses.
1274+
The reader seam defines normalized context states, not a receipt storage format.
1275+
1276+
Every API call is a read using the release job's own App token. Rate limits
1277+
and upstream 5xx responses refuse immediately, naming the failure, without
1278+
sleeping or retrying; empty or unparseable evidence also refuses.

‎scripts/release_gate.py‎

Lines changed: 153 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
#!/usr/bin/env python3
2-
"""Refuse a release unless its tree matches a merged, gate-green PR head.
2+
"""Refuse a release without full verification and parity evidence.
33
44
Usage: release_gate.py gate --repo OWNER/REPO --sha SHA --ref refs/heads/main
55
6-
All evidence comes from the live GitHub API, including both commit trees and
7-
the individual statuses on the matching PR head. ``main(api=callable)`` is the
8-
only test seam; tests supply raw API responses without spawning commands.
6+
Every GitHub API call is a read (GET), using the release job's own GH_TOKEN.
7+
Each endpoint/page is read at most once; failures refuse without retry or sleep.
8+
Phase 1 checks a unique tree-matching merged PR head. Phase 2 requires the exact
9+
main sha's proof receipt after the fixed watcher cut-over, with no PR fallback.
10+
Tests inject API and git callables and patch the read_main_proof seam.
911
"""
1012
from __future__ import annotations
1113

@@ -19,32 +21,84 @@
1921

2022

2123
CONTEXTS = ("pineforge/verify", "pineforge/parity")
24+
MAIN_PROOF_WATCHER_FIRST_SHA: str | None = None
25+
"""None = the watcher is not live yet. Otherwise its FIRST recorded main sha.
26+
27+
This cut-over is fixed in code and changed only by a reviewed PR, never by the
28+
release job, an environment variable or a workflow input.
29+
"""
2230
API = Callable[..., str]
31+
Git = Callable[[str, str], bool]
32+
# gh may print the next page's headers directly after a JSON array's closing ].
33+
_HTTP_RESPONSE = re.compile(
34+
r"(?:^|(?<=\]))HTTP/\S+ ([0-9]{3})[^\r\n]*\r?\n"
35+
r"(?:[A-Za-z0-9-]+:[^\r\n]*\r?\n)*\r?\n", re.MULTILINE)
2336

2437

2538
class ReleaseGateError(ValueError):
2639
"""Missing, red or unreadable release evidence; never an advisory failure."""
2740

2841

2942
def gh_api(endpoint: str, *, paginate: bool = False, jq: str | None = None) -> str:
30-
command = ["gh", "api", endpoint]
43+
command = ["gh", "api", endpoint, "--include"]
3144
if paginate:
3245
command.append("--paginate")
3346
if jq is not None:
3447
command.extend(["--jq", jq])
3548
return subprocess.run(command, check=True, capture_output=True, text=True).stdout
3649

3750

51+
def _http_failure(raw: str, *, exception: bool = False) -> str | None:
52+
codes = [int(match[1]) for match in _HTTP_RESPONSE.finditer(raw)]
53+
if exception:
54+
# gh reports failed reads as "(HTTP 403)" on stderr; HTTPError uses
55+
# "HTTP Error 503". stdout may still contain the response headers.
56+
codes.extend(int(code) for code in re.findall(
57+
r"\bHTTP(?: Error)?[ \t]+([0-9]{3})\b", raw, re.IGNORECASE))
58+
for code in codes:
59+
if 500 <= code <= 599:
60+
return f"upstream error {code}"
61+
if (re.search(r"^X-RateLimit-Remaining:[ \t]*0[ \t]*\r?$", raw,
62+
re.MULTILINE | re.IGNORECASE)
63+
or (403 in codes and re.search(r"rate[ -]+limit", raw, re.IGNORECASE))):
64+
return "rate limited"
65+
for code in codes:
66+
if not 200 <= code <= 299:
67+
return f"failed with HTTP {code}"
68+
return None
69+
70+
3871
def _read_text(api: API, endpoint: str, **options) -> str:
3972
try:
4073
raw = api(endpoint, **options)
4174
except subprocess.CalledProcessError as exc:
4275
detail = (exc.stderr or exc.stdout or str(exc)).strip()
43-
raise ReleaseGateError(f"API {endpoint} failed: {detail}") from exc
76+
reason = _http_failure(f"{exc.stdout or ''}\n{exc.stderr or ''}",
77+
exception=True) or "failed"
78+
raise ReleaseGateError(f"API {endpoint} {reason}: {detail}") from exc
4479
except Exception as exc:
45-
raise ReleaseGateError(f"API {endpoint} failed: {exc}") from exc
80+
reason = _http_failure(str(exc), exception=True) or "failed"
81+
raise ReleaseGateError(f"API {endpoint} {reason}: {exc}") from exc
4682
if not isinstance(raw, str):
4783
raise ReleaseGateError(f"API {endpoint} returned a non-text payload")
84+
reason = _http_failure(raw)
85+
if reason:
86+
raise ReleaseGateError(f"API {endpoint} {reason}")
87+
# --include emits one header block per page, also when --jq is used.
88+
# Preserve page boundaries so a good page cannot hide an empty response.
89+
responses = list(_HTTP_RESPONSE.finditer(raw))
90+
if responses:
91+
if raw[:responses[0].start()].strip() or (
92+
not options.get("paginate", False) and len(responses) != 1):
93+
raise ReleaseGateError(f"API {endpoint} returned unexpected HTTP responses")
94+
bodies = []
95+
for index, response in enumerate(responses):
96+
end = responses[index + 1].start() if index + 1 < len(responses) else len(raw)
97+
body = raw[response.end():end].strip()
98+
if not body:
99+
raise ReleaseGateError(f"API {endpoint} returned an empty payload")
100+
bodies.append(body)
101+
raw = "\n".join(bodies)
48102
if not raw.strip():
49103
raise ReleaseGateError(f"API {endpoint} returned an empty payload")
50104
return raw.strip()
@@ -94,7 +148,7 @@ def _commit_tree(api: API, repo: str, sha: str) -> str:
94148
return tree
95149

96150

97-
def _merged_pulls(api: API, repo: str, sha: str) -> list[tuple[datetime, int, str]]:
151+
def _merged_pulls(api: API, repo: str, sha: str) -> list[tuple[int, str]]:
98152
endpoint = f"repos/{repo}/commits/{sha}/pulls"
99153
merged = []
100154
for row in _read_json(api, endpoint, paginate=True):
@@ -103,21 +157,74 @@ def _merged_pulls(api: API, repo: str, sha: str) -> list[tuple[datetime, int, st
103157
if row["merged_at"] is None:
104158
continue
105159
try:
106-
merged_at = datetime.strptime(row["merged_at"], "%Y-%m-%dT%H:%M:%SZ")
160+
datetime.strptime(row["merged_at"], "%Y-%m-%dT%H:%M:%SZ")
107161
except (TypeError, ValueError) as exc:
108162
raise ReleaseGateError(
109163
f"API {endpoint} returned invalid merged_at: {row['merged_at']!r}") from exc
110164
number, head = row.get("number"), row.get("head")
111165
if (type(number) is not int or number <= 0 or not isinstance(head, dict)
112166
or not _is_sha(head.get("sha"))):
113167
raise ReleaseGateError(f"API {endpoint} returned invalid pull request: {row!r}")
114-
merged.append((merged_at, number, head["sha"]))
168+
if any(number == previous for previous, _ in merged):
169+
raise ReleaseGateError(f"API {endpoint} returned duplicate pull request #{number}")
170+
merged.append((number, head["sha"]))
115171
if not merged:
116172
raise ReleaseGateError(f"no merged pull request associated with {sha}")
117-
return sorted(merged, reverse=True)
173+
return merged
174+
175+
176+
def git_is_ancestor(ancestor: str, descendant: str) -> bool:
177+
result = subprocess.run(["git", "merge-base", "--is-ancestor", ancestor, descendant],
178+
check=False, capture_output=True, text=True)
179+
if result.returncode not in (0, 1):
180+
raise ReleaseGateError(
181+
f"git merge-base --is-ancestor failed: {result.stderr.strip()}")
182+
return result.returncode == 0
183+
184+
185+
def read_main_proof(repo: str, sha: str) -> dict | None:
186+
"""Return normalized context -> state evidence for this exact repo/main sha.
187+
188+
This seam defines no receipt storage format; C2 supplies the reader that
189+
binds the receipt to the requested sha. None means no receipt was recorded.
190+
"""
191+
raise NotImplementedError("phase 2 receipt reader lands with C2 main-watch #176")
192+
193+
194+
def _uses_main_proof(sha: str, git: Git) -> bool:
195+
first = MAIN_PROOF_WATCHER_FIRST_SHA
196+
if first is None:
197+
return False
198+
if not _is_sha(first):
199+
raise ReleaseGateError("invalid MAIN_PROOF_WATCHER_FIRST_SHA cut-over")
200+
try:
201+
after = git(first, sha)
202+
if type(after) is not bool:
203+
raise ReleaseGateError("invalid git ancestry result for main-proof cut-over")
204+
if after:
205+
return True
206+
before = git(sha, first)
207+
if type(before) is not bool:
208+
raise ReleaseGateError("invalid git ancestry result for main-proof cut-over")
209+
if before:
210+
return False
211+
except Exception as exc:
212+
raise ReleaseGateError(f"cannot determine main-proof cut-over ancestry: {exc}") from exc
213+
raise ReleaseGateError(f"release sha {sha} is unrelated to main-proof cut-over {first}")
118214

119215

120-
def gate(repo: str, sha: str, ref: str, *, api: API) -> str:
216+
def _require_full_contexts(latest: dict, subject: str) -> str:
217+
# Exact names only: no prefix match and no lite-context fallback.
218+
for context in CONTEXTS:
219+
if context not in latest:
220+
raise ReleaseGateError(f"{subject}: missing {context}")
221+
if latest[context] != "success":
222+
raise ReleaseGateError(
223+
f"{subject}: {context}={latest[context]} (expected success)")
224+
return "; ".join(f"{context}={latest[context]}" for context in CONTEXTS)
225+
226+
227+
def gate(repo: str, sha: str, ref: str, *, api: API, git: Git = git_is_ancestor) -> str:
121228
if ref != "refs/heads/main":
122229
raise ReleaseGateError(f"release requires refs/heads/main, got {ref}")
123230
if re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repo) is None:
@@ -132,13 +239,38 @@ def gate(repo: str, sha: str, ref: str, *, api: API) -> str:
132239
if current != sha:
133240
raise ReleaseGateError(f"release sha {sha} is not current main head {current}")
134241

242+
if _uses_main_proof(sha, git):
243+
subject = f"main-proof receipt for {sha}"
244+
try:
245+
proof = read_main_proof(repo, sha)
246+
except Exception as exc:
247+
raise ReleaseGateError(f"{subject} unreadable: {exc}") from exc
248+
if proof is None:
249+
raise ReleaseGateError(f"main-proof receipt is missing for {sha}")
250+
if (not isinstance(proof, dict) or not proof
251+
or any(not isinstance(context, str) or not context
252+
or not isinstance(state, str) or not state
253+
for context, state in proof.items())):
254+
raise ReleaseGateError(f"{subject}: invalid or empty context map")
255+
states = _require_full_contexts(proof, subject)
256+
return f"release gate green: {subject}; {states}"
257+
135258
merged = _merged_pulls(api, repo, sha)
136259
tree = _commit_tree(api, repo, sha)
137-
for _, number, head in merged:
138-
if _commit_tree(api, repo, head) == tree:
139-
break
140-
else:
260+
trees = {sha: tree}
261+
matches = []
262+
for number, head in merged:
263+
if head not in trees:
264+
trees[head] = _commit_tree(api, repo, head)
265+
if trees[head] == tree:
266+
matches.append((number, head))
267+
if len(matches) > 1:
268+
numbers = ", ".join(f"#{number}" for number, _ in sorted(matches))
269+
raise ReleaseGateError(
270+
f"ambiguous release tree {tree}: multiple merged PR heads match ({numbers})")
271+
if not matches:
141272
raise ReleaseGateError(f"no merged pull request head matches release tree {tree}")
273+
number, head = matches[0]
142274

143275
endpoint = f"repos/{repo}/commits/{head}/statuses?per_page=100"
144276
latest = {}
@@ -154,26 +286,21 @@ def gate(repo: str, sha: str, ref: str, *, api: API) -> str:
154286
if not isinstance(state, str) or not state:
155287
raise ReleaseGateError(f"API {endpoint} returned invalid status state for {context}")
156288
latest[context] = state
157-
for context in CONTEXTS:
158-
if context not in latest:
159-
raise ReleaseGateError(f"PR #{number} head {head}: missing {context}")
160-
if latest[context] != "success":
161-
raise ReleaseGateError(
162-
f"PR #{number} head {head}: {context}={latest[context]} (expected success)")
163-
states = "; ".join(f"{context}={latest[context]}" for context in CONTEXTS)
289+
states = _require_full_contexts(latest, f"PR #{number} head {head}")
164290
return f"release gate green: PR #{number} head {head}; {states}; tree {tree}"
165291

166292

167-
def main(argv=None, *, api: API | None = None) -> int:
293+
def main(argv=None, *, api: API | None = None, git: Git | None = None) -> int:
168294
parser = argparse.ArgumentParser(description=__doc__)
169295
modes = parser.add_subparsers(dest="mode", required=True)
170-
check = modes.add_parser("gate", help="require a tree-matching, gate-green merged PR")
296+
check = modes.add_parser("gate", help="require full release proof for the current main sha")
171297
check.add_argument("--repo", required=True)
172298
check.add_argument("--sha", required=True)
173299
check.add_argument("--ref", required=True)
174300
args = parser.parse_args(argv)
175301
try:
176-
green = gate(args.repo, args.sha, args.ref, api=api if api is not None else gh_api)
302+
green = gate(args.repo, args.sha, args.ref, api=api if api is not None else gh_api,
303+
git=git if git is not None else git_is_ancestor)
177304
except ReleaseGateError as exc:
178305
print(f"::error::{exc}", file=sys.stderr)
179306
return 1

0 commit comments

Comments
 (0)