Skip to content

Commit ad1ebac

Browse files
luisleo526claude
andauthored
ci(release): require full verify + parity green before an engine release (C2) (#479)
* ci(release): require gate-green merged PR tree before release * 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. * ci(release): use CI-only gate module names * ci(release): pin required status creators * ci(release): build prebuilts from the emitted commit sha * ci(release): bind PR evidence to the current main merge Read main through the branch endpoint, filter merged PR candidates by base and merge commit, and leave empty-list decisions to evidence consumers. * test(ci): pin exact release refs and proof configuration * docs(ci): document immutable release tags and recovery Records the live engine tag ruleset and how recovery works against it: ruleset 25591564 "release tags immutable (v*)" covers refs/tags/v* with update and deletion rules, no bypass actors, active; creation stays allowed, so release.yml's annotated-tag push is unchanged; a recovery needing a v* tag deleted or moved is an explicit human admin edit of that ruleset, and nothing in this repository may assume it can re-tag. Rewords the earlier line "L6 adds a separate tag ruleset forbidding updates and deletion of `v*` tags." from future tense to present, because the ruleset is live now (its subject is unchanged; the new text points at the new section). * test(ci): match continue-on-error as a YAML key, not as comment text test_prebuilt_requires_release_success_without_failure_bypasses asserted that the word "continue-on-error" does not occur in the prebuilt job's text. ci_preflight._jobs() slices a job up to the next job key, so that text ends with the comment block of the notify-hub job ("FAIL LOUD (no continue-on-error): ..."), and the cloud preflight of PR #479's head failed its release-gate-tests stage on a word in a comment. The workflow has no continue-on-error key in the release or prebuilt job. The pin now runs on the job text with comment-only lines removed and matches a real `continue-on-error:` key, `always(` and `!cancelled(`. A second test applies a real `continue-on-error: true` line and a real `if: ${{ always() }}` line to the prebuilt job of the unmodified workflow and requires the same assertions to refuse each one, while the unmodified workflow, comment included, is accepted. No workflow, gate or preflight code changed. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent c32c732 commit ad1ebac

5 files changed

Lines changed: 1326 additions & 2 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ jobs:
8181

8282
outputs:
8383
tag: ${{ steps.bump.outputs.tag }}
84+
sha: ${{ steps.publish.outputs.sha }}
8485
version: ${{ steps.bump.outputs.next }}
8586
prerelease: ${{ steps.bump.outputs.prerelease }}
8687

@@ -110,6 +111,17 @@ jobs:
110111
git config user.name "github-actions[bot]"
111112
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
112113
114+
- name: Refuse unless pineforge/verify and pineforge/parity are green
115+
id: gate
116+
env:
117+
GH_TOKEN: ${{ steps.app.outputs.token }}
118+
GITHUB_REPOSITORY: ${{ github.repository }}
119+
GITHUB_SHA: ${{ github.sha }}
120+
GITHUB_REF: ${{ github.ref }}
121+
run: |
122+
python3 scripts/ci_release_gate.py gate \
123+
--repo "${GITHUB_REPOSITORY}" --sha "${GITHUB_SHA}" --ref "${GITHUB_REF}"
124+
113125
# current / next / tag / prerelease / previous (the release-notes base),
114126
# validated; see scripts/release_version.py.
115127
- name: Compute next version
@@ -203,6 +215,7 @@ jobs:
203215
# notes step writes them; the prebuilt and notify-hub jobs need it and
204216
# did not run.
205217
- name: Write bumped VERSION, commit, tag, push
218+
id: publish
206219
if: ${{ !inputs.dry_run }}
207220
env:
208221
NEXT: ${{ steps.bump.outputs.next }}
@@ -217,6 +230,7 @@ jobs:
217230
git tag -a "${TAG}" -m "Release ${TAG}"
218231
python3 scripts/gen_run_failure_catalog_diff.py --check
219232
git push --atomic origin HEAD "${TAG}"
233+
echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
220234
221235
# The range starts at scripts/release_version.py's `previous`: the last
222236
# tag below this release in semver order (git's v:refname sort puts
@@ -355,12 +369,25 @@ jobs:
355369

356370
steps:
357371
# A dry run has no tag yet: it builds the dispatched commit.
358-
- name: Checkout tag
372+
- name: Checkout release commit
359373
uses: actions/checkout@v4
360374
with:
361-
ref: ${{ inputs.dry_run && github.sha || needs.release.outputs.tag }}
375+
ref: ${{ inputs.dry_run && github.sha || needs.release.outputs.sha }}
362376
fetch-depth: 0 # the version helper still observes the git sha
363377

378+
- name: Assert tag still names the emitted release commit
379+
if: ${{ !inputs.dry_run }}
380+
env:
381+
TAG: ${{ needs.release.outputs.tag }}
382+
SHA: ${{ needs.release.outputs.sha }}
383+
run: |
384+
set -euo pipefail
385+
if [[ ! "${SHA}" =~ ^[0-9a-f]{40}$ ]]; then
386+
echo "::error::invalid emitted release sha: ${SHA}" >&2
387+
exit 1
388+
fi
389+
test "$(git rev-parse "refs/tags/${TAG}^{commit}")" = "${SHA}"
390+
364391
- name: Write the dry run's VERSION
365392
if: ${{ inputs.dry_run }}
366393
env:

‎docs/ci.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1251,3 +1251,68 @@ split. Cancelled/failed jobs did skip the old compiler post-save, which reduced
12511251
cache freshness; the new save ordering addresses that independently. The
12521252
historical ASan startup assertion remains a separate diagnosis, and splitting
12531253
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. The guard reads `repos/{repo}/branches/main` (`.commit.sha`)
1261+
and requires the release sha to equal that branch's current head. It requires
1262+
exactly one associated merged PR targeting `main`, with `merge_commit_sha`
1263+
equal to the release sha and a head tree matching the released tree, then
1264+
reads that head's full contexts through the statuses API. PRs targeting other
1265+
bases or naming a different merge commit are ignored; malformed fields refuse.
1266+
Zero matches refuse; multiple matches refuse and name every matching PR, with
1267+
no preference for the newest.
1268+
1269+
Phase 2 is **not live yet**: `MAIN_PROOF_WATCHER_FIRST_SHA` in
1270+
`scripts/ci_release_gate.py` is `None`. When C2 main-watch (#176) supplies the
1271+
receipt reader, the cut-over is the watcher's **first recorded main sha**,
1272+
fixed in that constant by a reviewed PR. The release job cannot configure it
1273+
through an environment variable or workflow input. At that sha and every
1274+
descendant, the guard requires a main-proof receipt for the **exact main
1275+
sha** with both full contexts green and does not consult PR heads. Missing,
1276+
unreadable or non-green receipts refuse, with no transitional fallback.
1277+
Commits preceding the cut-over retain phase 1; unknown ancestry refuses.
1278+
The reader seam defines normalized context states, not a receipt storage format.
1279+
1280+
Every API call is a read using the release job's own App token. Rate limits
1281+
and upstream 5xx responses refuse immediately, naming the failure, without
1282+
sleeping or retrying; empty or unparseable evidence also refuses. An empty JSON
1283+
array is a valid list response; each caller refuses if its required PR or
1284+
context evidence is absent. An empty single-object payload still refuses.
1285+
1286+
Prebuilt jobs build the commit sha emitted after the release job's atomic
1287+
push, and assert that the release tag still resolves to that sha before
1288+
building. A missing or malformed sha or a changed tag fails the job. Dry runs
1289+
build `github.sha` and skip the tag assertion because no tag exists. A
1290+
separate tag ruleset forbids updates and deletion of `v*` tags; see "Release
1291+
tag immutability and recovery" below.
1292+
1293+
#### Release tag immutability and recovery
1294+
1295+
Release tags `v*` are protected by active GitHub ruleset `25591564`
1296+
(`release tags immutable (v*)`), with `update` and `deletion` rules and no
1297+
bypass actors. Creating a new `v*` tag is still allowed, so the workflow's
1298+
annotated-tag push is unchanged. Moving or deleting an existing `v*` tag is
1299+
refused for every workflow, script and token.
1300+
1301+
Any recovery that requires deleting or moving a `v*` tag now requires a
1302+
human administrator to explicitly edit ruleset `25591564`; nothing in this
1303+
repository may assume it can re-tag. The workflow's
1304+
["Refuse if tag already exists" step in `release.yml`](../.github/workflows/release.yml#L140)
1305+
also refuses an existing tag before creating one.
1306+
1307+
#### Allowed status creators
1308+
1309+
In phase 1, the newest statuses API row for each full context must have a
1310+
`creator.login` and `creator.type` pair in `ALLOWED_STATUS_CREATORS` in
1311+
`scripts/ci_release_gate.py`. Missing or malformed creators and every other
1312+
identity refuse, even when an older row from an allowed creator succeeded.
1313+
1314+
| Login | Type | Confirmed producer |
1315+
| --- | --- | --- |
1316+
| `luisleo526` | `User` | The operator PAT that posts `pineforge/verify` / `pineforge/parity` via `lab verify record` / `lab verify parity`. |
1317+
1318+
Adding a creator is a code change reviewed like any other.

‎scripts/ci_preflight.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1123,6 +1123,7 @@ def check_commands(source: Path, output: Path | None = None,
11231123
[sys.executable, str(source / 'scripts/test_report_outputs_keys.py')]),
11241124
('release-version-tests',
11251125
[sys.executable, str(source / 'scripts/test_release_version.py')]),
1126+
('release-gate-tests', [sys.executable, str(source / 'scripts/test_ci_release_gate.py')]),
11261127
# R5 run-failure codes: the catalog diff release.yml stamps is a tested
11271128
# script, and the code tables of docs/pages/run-failure-codes.md are
11281129
# generated from the catalog it diffs.

0 commit comments

Comments
 (0)