Skip to content

Commit 511abc5

Browse files
authored
Merge #818 into the engine 1.11.1 train
ci: split release bump and tag admission
2 parents 1eab934 + d42bc21 commit 511abc5

10 files changed

Lines changed: 6151 additions & 511 deletions

‎.github/workflows/release.yml‎

Lines changed: 142 additions & 66 deletions
Large diffs are not rendered by default.

‎docs/ci.md‎

Lines changed: 102 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1849,10 +1849,25 @@ judge the exact pull request head tree.
18491849

18501850
### Release guard phases
18511851

1852-
The release guard requires exactly `pineforge/verify` and `pineforge/parity`
1853-
to be `success`; lite variants never satisfy either requirement. Phase 1 is
1854-
the **transitional** merged-PR-head path for main commits that predate the
1855-
main watcher. The guard reads `repos/{repo}/branches/main` (`.commit.sha`)
1852+
Release admission requires `pineforge/parity=success`; lite variants never
1853+
satisfy that requirement. `pineforge/verify` remains advisory and its actual
1854+
presence and latest authenticated state are printed and retained in the receipt.
1855+
The existing `lab verify record` producer posts that status. The `ci_verify.py`
1856+
profiles inside ci-post remain separate execution evidence and never supply a
1857+
missing status. On the future main-proof path, the reader's context map supplies
1858+
verify; an absent entry is explicitly `presence=false`, `state=missing`.
1859+
1860+
Dispatch phase `bump` checks the current main SHA and pushes only the untagged
1861+
two-file VERSION/catalog-reset commit. Wait for that bump's own full ci-post,
1862+
then dispatch phase `tag` on it with `dispatch_sha` equal to its sole parent.
1863+
Tag admission checks both authenticated API trees and the local committed
1864+
transition; tagging reuses that exact bump SHA and never increments VERSION.
1865+
Phase `bump` refuses an existing bump without a merged PR on both the PR and
1866+
future main-proof paths: dispatch that existing bump with phase `tag`.
1867+
Dry runs use the same admission and record their actual dry-run flag.
1868+
1869+
The **transitional** merged-PR-head path applies before the main watcher.
1870+
The guard reads `repos/{repo}/branches/main` (`.commit.sha`)
18561871
and requires the release sha to equal that branch's current head. It requires
18571872
exactly one associated merged PR targeting `main`, with `merge_commit_sha`
18581873
equal to the release sha and a head tree matching the released tree, then
@@ -1862,21 +1877,24 @@ When qualifying merged PRs exist, zero tree matches refuse; multiple matches
18621877
refuse and name every matching PR, with no preference for the newest. A failed
18631878
tree or status check never falls back to a release bump.
18641879

1865-
When there is no qualifying merged PR for the current main sha, phase 1 permits
1866-
one release bump only when all three conditions hold:
1880+
The legacy phase-less read-only interface can admit an existing release bump
1881+
without a qualifying merged PR. Explicit phase `tag` additionally binds its
1882+
sole parent to the phase-1 dispatch SHA. Both require all three conditions:
18671883

18681884
1. GitHub's `repos/{repo}/actions/runs?head_sha=<sha>&per_page=100` returns at
18691885
least one run with `event == "push"`, `head_branch == "main"` and
1870-
`head_sha == <sha>`. Every such run must have both `actor.login` and
1871-
`triggering_actor.login` equal to the gate's fixed `RELEASE_PUSH_ACTOR`,
1872-
`pineforge-app[bot]`, the release App installation token used by
1873-
`release.yml`. All pages are read; missing HTTP headers, malformed pages,
1886+
`head_sha == <sha>`. Every such run's original `actor.login` must equal
1887+
the fixed `RELEASE_PUSH_ACTOR`, `pineforge-app[bot]`, the release App used
1888+
by `release.yml`. A maintainer may trigger a rerun: the gate authenticates
1889+
that actor's repository `admin`, `maintain` or `write` permission through
1890+
the collaborator-permission API, without guessing a role from a login.
1891+
All pages are read; missing HTTP headers, malformed pages,
18741892
an advertised unread Link next page, changing `total_count` or a row count
18751893
different from that total refuse. A matching count never overrides an
18761894
unread next page. Reaching the filtered API's 1000-run limit also refuses,
18771895
because completeness at that boundary cannot be inferred. Zero matching
18781896
runs refuse. A bump pushed seconds
1879-
ago may not have a post-merge run yet; retry the release once that push run exists.
1897+
ago may not have a post-merge run yet; dispatch tag after that push run exists.
18801898
At gate time, the guard also reads `repos/{repo}` to confirm main is still
18811899
the default branch, lists `repos/{repo}/rulesets?includes_parents=true&per_page=100`
18821900
with every page, and reads each branch ruleset by id for its conditions,
@@ -1912,8 +1930,9 @@ one release bump only when all three conditions hold:
19121930
Empty bodies refuse with `returned an empty payload`; a valid empty JSON
19131931
array is still a complete document.
19141932
2. The bump has exactly one parent, and that parent passes the ordinary
1915-
phase-1 merged-PR/tree/full-status checks above, including the allowed
1916-
status creator. This depth is exactly one: a bump on another bump refuses
1933+
merged-PR/tree/parity checks above, including the allowed status creator,
1934+
or its exact main-proof receipt after the fixed cut-over.
1935+
This depth is exactly one: a bump on another bump refuses
19171936
even when its grandparent was gated. A merge commit also refuses.
19181937
3. The complete parent-to-bump file diff is exactly `VERSION` and
19191938
`docker/run_failure_codes_diff.json`, both status `M`, both regular blobs
@@ -1929,7 +1948,69 @@ the App credential by this workflow. Commit author, committer and verification
19291948
metadata provide no push-identity evidence. Condition 3 bounds the content
19301949
changes to the two files whose values the release workflow computes: the next
19311950
version and the reset catalog diff. Preflight pins the exact writer, staging,
1932-
commit and atomic-push step and the App-token checkout wiring.
1951+
commit and phased push step and the App-token checkout wiring.
1952+
1953+
The complete default latest jobs API response for the selected exact-SHA run
1954+
is the proving inventory. Required names must all succeed; any red job and any
1955+
duplicate name in that inventory refuse. Every attempt from 1 through the
1956+
actual `run_attempt` is separate audit history, including failed and cancelled
1957+
attempts, duplicate historical names, null conclusions, job IDs, triggering
1958+
actors, timestamps and steps. Attempt-specific metadata supplies attribution;
1959+
complete job pagination and counts are required for each inventory.
1960+
New IDs and a current API attempt number do not establish fresh execution.
1961+
Identical non-null timestamps and steps under a unique name may produce an
1962+
explicit derived carried association, without inventing a physical attempt.
1963+
Missing, unreadable or gapped history refuses and stays marked incomplete.
1964+
There is no deterministic-failure retry waiver.
1965+
1966+
Each attempt's metadata and paginated jobs, and the latest proving inventory,
1967+
retain SHA256 identities of the original binary `gh api --include` stdout.
1968+
The whole-response digest includes all emitted headers, bodies and separators;
1969+
ordered page digests cover each HTTP header through the byte before the next
1970+
header (the first includes any prefix, the last includes trailing bytes).
1971+
These are CLI response bytes, not wire HTTP bytes or re-encoded JSON. Hashes
1972+
are computed before decoding, stripping or parsing; raw headers and bodies
1973+
are excluded from the receipt. Unframed injected fixtures are one response.
1974+
Each entry names its run, requested attempt, endpoint and purpose; `complete`
1975+
means the response parsed with complete pagination, not policy success.
1976+
Admission and refusal bind the ordered `response_inventory` with a separate
1977+
`canonical-response-inventory/v1` SHA256 over its UTF-8 JSON (`sort_keys=True`,
1978+
`separators=(",", ":")`, `ensure_ascii=True`); this is a manifest digest.
1979+
1980+
Before collecting a run's jobs, the gate reads its current metadata and
1981+
requires it to match the selected inventory row. Immediately before admission,
1982+
it reads each relied-on run once more through the underlying transport,
1983+
bypassing the collection cache, with the selected proof last. This covers docs,
1984+
passed-over proof candidates and App-push evidence, deduplicated by repository
1985+
and run id. A changed attempt, unreadable response or mismatched run identity,
1986+
actors, status or conclusion refuses with nonzero exit and empty success stdout.
1987+
The receipt keeps initial/final attempts, response digests and incomplete
1988+
validation on refusal. Collection completeness remains relative to the initial
1989+
attempt. This bounded second metadata read is validation, not a retry; all
1990+
other endpoint reads remain one-pass, without retries or sleeps.
1991+
1992+
Docs-only releases use `ci_docs_only.is_documentation`, the shared merge
1993+
classifier, to walk back to the first non-doc commit's actual full CI proof.
1994+
Each intervening docs SHA still needs its own latest successful ci-post run;
1995+
a red or missing docs run cannot be rescued by an ancestor. Empty changes stop
1996+
the walk; unreadable paths/parents and more than 20 docs commits refuse. The requested
1997+
release SHA/tree, built proof SHA/tree and classified docs chain remain
1998+
distinct in the receipt. A VERSION bump is non-doc and needs its own full run.
1999+
The packaged-input control derives source headers, generated version/config/
2000+
targets, libraries and copied roots from CMake install rules, `release.yml`
2001+
and the x86 staging helper; unsupported rules refuse.
2002+
2003+
The gate optionally writes `--receipt FILE` from the same collected evidence
2004+
on admission or refusal. Refusal stays nonzero; a receipt write failure also
2005+
fails admission. The workflow always uploads exactly
2006+
`${{ runner.temp }}/release-gate-receipt.json` as
2007+
`release-gate-<phase>-<run_id>-<run_attempt>` for seven days, including dry runs.
2008+
The allowlisted JSON records identities, authenticated parity, actual advisory
2009+
verify, App provenance, proving jobs, complete attempt history and limits.
2010+
Safe refusal reasons name the failed checkpoint and error class; exception
2011+
representations, credentials, private source and authorization headers are excluded.
2012+
Limits are ten candidate proof runs, 100 attempts per run, 10,000 jobs per
2013+
inventory and refusal at the filtered API's 1000-run boundary.
19332014

19342015
The gate needs `bypass_actors` visible on every branch ruleset in the inventory.
19352016
If the release App token cannot see them, the bump is refused.
@@ -1977,8 +2058,10 @@ receipt reader, the cut-over is the watcher's **first recorded main sha**,
19772058
fixed in that constant by a reviewed PR. The release job cannot configure it
19782059
through an environment variable or workflow input. At that sha and every
19792060
descendant, the guard requires a main-proof receipt for the **exact main
1980-
sha** with both full contexts green and does not consult PR heads. Missing,
1981-
unreadable or non-green receipts refuse, with no PR or release-bump fallback.
2061+
sha** with parity green and does not consult PR-head statuses. Missing,
2062+
unreadable or red parity receipts refuse, with no PR or release-bump fallback.
2063+
Advisory verify is retained from that exact context map, including missing or red.
2064+
Phase `bump` still requires an associated merged PR and refuses a re-bump.
19822065
Commits preceding the cut-over retain phase 1; unknown ancestry refuses.
19832066
The reader seam defines normalized context states, not a receipt storage format.
19842067

@@ -1988,7 +2071,7 @@ sleeping or retrying; empty or unparseable evidence also refuses. An empty JSON
19882071
array is a valid list response; each caller refuses if its required PR or
19892072
context evidence is absent. An empty single-object payload still refuses.
19902073

1991-
Prebuilt jobs build the sha emitted after the release job's atomic push and assert that the release tag still resolves to it before building.
2074+
Prebuilt jobs build the SHA emitted by phase `tag` and assert that the release tag still resolves to it before building.
19922075
A missing/malformed sha or changed tag fails. Dry runs build `github.sha` and skip the tag assertion because no tag exists.
19932076
A separate tag ruleset forbids updates and deletion of `v*` tags; see "Release tag immutability and recovery" below.
19942077
After packing, x86_64 checks the emitted tarball's SHA-256 sidecar and unpacks those exact bytes in the pinned Bookworm environment before upload.
@@ -2006,7 +2089,7 @@ refused for every workflow, script and token.
20062089
Any recovery that requires deleting or moving a `v*` tag now requires a
20072090
human administrator to explicitly edit ruleset `25591564`; nothing in this
20082091
repository may assume it can re-tag. The workflow's
2009-
["Refuse if tag already exists" step in `release.yml`](../.github/workflows/release.yml#L140)
2092+
["Refuse if tag already exists" step in `release.yml`](../.github/workflows/release.yml#L183)
20102093
also refuses an existing tag before creating one.
20112094

20122095
#### Allowed status creators
@@ -2056,7 +2139,7 @@ The scanner runs actionlint before its structural text rules.
20562139
The main branch rule table and parser grammar judge the fetched head workflows.
20572140
A workflow change that needs a loosened rule must therefore use two changes.
20582141

2059-
Rule and table changes land first while existing workflows pass; workflow changes follow, so one PR cannot change both sides of admission.
2142+
Rule and table changes land first while existing workflows pass; workflow changes follow, so one PR cannot change both sides of admission; STEP1 is the rules half for the complete current split and planned split+phase contracts, with workflow activation subject to the later composed main change.
20602143
`gke-pr.yml` admits two independent variants, each with OLD and NEW shapes.
20612144
For arm, OLD omits `build-arm`, so earlier workflow files still pass; defining that job selects all arm NEW checks together.
20622145
Arm NEW requires the exact arm classifier output, fixed Debug job on `ubuntu-24.04-arm`, arm-aware `legs` needs/check and independent `result` check.

‎docs/reference/merge-gate-and-promotion.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,3 +17,36 @@ squash-merged, so the head itself never lands on `main`), both required
1717
statuses are success on that head, and the maintainers' private campaign tool finds the merge gate's
1818
parity verdict for that tree; it then adopts the pair that verdict measured.
1919
Anything else exits green without promoting.
20+
21+
## Release admission and retained evidence
22+
23+
Release admission requires authenticated `pineforge/parity=success`.
24+
`pineforge/verify` stays advisory: its existing producer still runs, and its
25+
actual latest state and presence are printed and recorded. The profiles run
26+
by ci-post are execution evidence, separate from that status. The future
27+
main-proof context map supplies verify on that path; no entry means
28+
`presence=false`, `state=missing`, never an inferred success.
29+
30+
Phase `bump` gates current main and pushes only the untagged VERSION/catalog
31+
reset. After that bump's own full ci-post, phase `tag` names its sole checked
32+
parent with `dispatch_sha` and tags the same bump SHA. Both PR and future
33+
main-proof admission refuse a re-bump. The original push actor must be the
34+
release App; a maintainer's rerun requires authenticated repository write
35+
permission. Every attempt remains visible, including failed and cancelled
36+
attempts and incomplete history, which refuses admission.
37+
38+
The complete default latest jobs response for the selected exact-SHA run
39+
is the proving inventory; attempt-specific inventories are audit history.
40+
Any red proving job, duplicate proving name or missing required success
41+
refuses. Changed IDs/API attempt numbers do not establish fresh execution.
42+
Docs-only releases walk back with the shared `ci_docs_only.is_documentation`
43+
classifier to the actual built proof; each docs commit needs its own latest
44+
successful run. Requested release and proof SHA/tree identities and the docs
45+
chain stay distinct. VERSION bumps need their own full CI.
46+
47+
The optional gate receipt uses the decision's collected evidence, including
48+
actual advisory status, App attribution, proving jobs, all attempts and limits.
49+
Refusal remains nonzero and receipt-write failure fails the run.
50+
The workflow always retains that receipt for both phases and dry runs;
51+
it introduces no status producer or main-proof issuer. See
52+
[`docs/ci.md`](../ci.md#release-guard-phases) for limits and artifact details.

0 commit comments

Comments
 (0)