fix(release): drive checkpoint releases from frozen branches

Use branch pushes for Release Please preparation and reviewed-merge publication.
Reject moved source refs before tagging and bind registry provenance to the
triggering release commit. Remove phase inputs and document the three steps.

Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)
Assisted-by: Cirno (gensokyo-skills:cirno-radical-simplification)
This commit is contained in:
N0zoM1z0
2026-10-07 17:02:03 +00:00
parent 49887f0239
commit fc58fa1eb0
4 changed files with 127 additions and 111 deletions
+17 -39
View File
@@ -1,24 +1,15 @@
name: Release
on:
push:
branches: ["release/*"]
workflow_dispatch:
inputs:
release_branch:
description: Frozen release branch (release/VERSION)
required: true
type: string
phase:
description: Prepare the release PR, or publish its reviewed merge
required: true
default: prepare
type: choice
options: [prepare, publish]
env:
HUSKY: "0"
concurrency:
group: release-${{ inputs.release_branch }}
group: release-${{ github.ref }}
cancel-in-progress: false
jobs:
@@ -37,27 +28,22 @@ jobs:
shell: bash
env:
GH_TOKEN: ${{ github.token }}
RELEASE_BRANCH: ${{ inputs.release_branch }}
RELEASE_PHASE: ${{ inputs.phase }}
RELEASE_BRANCH: ${{ github.ref_name }}
run: |
if [[ "${RELEASE_PHASE}" == prepare && "${GITHUB_REF}" != "refs/heads/main" ]]; then
echo "Run prepare from main; release_branch selects the frozen source." >&2
exit 1
fi
if [[ "${RELEASE_PHASE}" == publish && "${GITHUB_REF}" != "refs/heads/${RELEASE_BRANCH}" ]]; then
echo "Run publish from the selected frozen release branch so npm provenance records its source." >&2
exit 1
fi
if [[ "${RELEASE_BRANCH}" != release/* ]]; then
echo "release_branch must select a release/ branch; main is not a release checkpoint." >&2
if [[ "${GITHUB_REF}" != "refs/heads/${RELEASE_BRANCH}" || "${RELEASE_BRANCH}" != release/* ]]; then
echo "Select a release/ branch; main and tags are not release checkpoints." >&2
exit 1
fi
if ! git check-ref-format "refs/heads/${RELEASE_BRANCH}"; then
echo "Invalid release_branch: ${RELEASE_BRANCH}" >&2
echo "Invalid release branch: ${RELEASE_BRANCH}" >&2
exit 1
fi
gh api "repos/${GITHUB_REPOSITORY}/git/ref/heads/${RELEASE_BRANCH}" \
--jq '.object.sha'
selected_sha="$(gh api "repos/${GITHUB_REPOSITORY}/git/ref/heads/${RELEASE_BRANCH}" --jq '.object.sha')"
if [[ "${selected_sha}" != "${GITHUB_SHA}" ]]; then
echo "The release branch moved after this run was triggered; review its new checkpoint before publication." >&2
exit 1
fi
printf 'Selected release checkpoint: %s\n' "${selected_sha}"
- uses: googleapis/release-please-action@v4
id: release
@@ -65,24 +51,16 @@ jobs:
# A dedicated credential lets release-PR updates trigger CI. GitHub
# requires manual approval for pull_request events from GITHUB_TOKEN.
token: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
target-branch: ${{ inputs.release_branch }}
skip-github-release: ${{ inputs.phase == 'prepare' }}
skip-github-pull-request: ${{ inputs.phase == 'publish' }}
target-branch: ${{ github.ref_name }}
- name: Require a merged release PR for publication
if: inputs.phase == 'publish' && steps.release.outputs.release_created != 'true'
run: |
echo "No new release was created. Merge the reviewed release PR into its frozen branch before publishing. For a partial publication, re-run failed jobs in the original run." >&2
exit 1
- name: Bind publication to the dispatched checkpoint
if: inputs.phase == 'publish' && steps.release.outputs.release_created == 'true'
- name: Bind publication to the triggering checkpoint
if: steps.release.outputs.release_created == 'true'
shell: bash
env:
RELEASE_SHA: ${{ steps.release.outputs.sha }}
run: |
if [[ "${RELEASE_SHA}" != "${GITHUB_SHA}" ]]; then
echo "The tagged release SHA differs from the dispatched checkpoint; refusing to publish mismatched source provenance." >&2
echo "The tagged release SHA differs from the triggering checkpoint; refusing to publish mismatched source provenance." >&2
exit 1
fi
+3 -3
View File
@@ -121,9 +121,9 @@ Describe the behavior change and verification performed in the pull request. Nev
## Maintainer release checklist
Use the [checkpoint release guide](docs/releasing.md). Releases start from an
explicit `release/VERSION` branch cut at a recorded commit. Manually prepare
the bot PR, wait for its exact-head CI and review, merge into that frozen
branch, and manually publish through the official Release workflow. Main
explicit `release/VERSION` branch cut at a recorded commit. Pushing the branch prepares
the bot PR. Wait for its exact-head CI and review; merging into that frozen
branch triggers publication through the official Release workflow. Main
pushes do not update release PRs or publish packages. Both publishers build
the exact SHA tagged by Release Please.
+33 -37
View File
@@ -1,10 +1,10 @@
# Releasing from a checkpoint
REA releases use an explicit source checkpoint. Main can continue accepting
REA releases use a frozen source checkpoint. Main can continue accepting
changes while a release is tested and published. The Release workflow runs
only when a maintainer dispatches it; main pushes do not refresh release PRs.
on `release/*` branches; main pushes do not refresh release PRs.
## 1. Select the source
## 1. Cut the release branch
Choose the next version from the unreleased Conventional Commits, including
breaking changes. Record the full source SHA and create `release/VERSION` at
@@ -25,47 +25,43 @@ older checkpoint, backport only the release infrastructure first and record
that additional commit. Do not merge later implementation changes into the
release branch or rebase the candidate onto a moving main.
## 2. Prepare the bot PR
Run the workflow definition from main and select the frozen source separately:
The branch push runs Release Please against that branch and opens a PR for
the version, changelog, and registry metadata. The generation step normalizes
the product catalog. To retry preparation after a failed run, select the same
frozen branch explicitly:
```bash
gh workflow run release.yml --ref main \
-f release_branch=release/5.0.0 -f phase=prepare
gh workflow run release.yml --ref release/5.0.0
```
Release Please targets that branch and prepares its version, changelog, and
registry metadata. The existing generation step normalizes the product
catalog. Preparation cannot create a GitHub release or publish a package.
## 2. Review and merge the bot PR
Record the final bot PR head after normalization. Approve GitHub-blocked bot
workflow runs for that head when needed.
workflow runs for that head when needed. Review the candidate's version,
notes, generated metadata, and package contents. Wait for the candidate's CI
and relevant real-provider checks. Routine local iterations need focused
checks; CI owns full deterministic coverage and platform lanes. If an artifact
or real-provider check is unavailable, report that limit before deciding to
publish.
Review the candidate's version, notes, generated metadata, and package
contents. Wait for the candidate's CI and relevant real-provider checks.
Routine local iterations need focused checks; CI owns full deterministic
coverage and platform lanes. If an artifact or real-provider check is
unavailable, report that limit before deciding to publish.
Merge the reviewed PR into `release/5.0.0` with its head SHA matched. **This
merge authorizes and triggers publication.** Further main commits do not change
this candidate. Do not push or merge anything else into the release branch
while publication is running. A necessary release fix must be reviewed and
tested before the bot PR merges and establishes a new recorded checkpoint.
Merge the reviewed PR into `release/5.0.0` with its head SHA matched. Further
main commits do not change this candidate. A necessary release fix belongs
on the release branch, must be reviewed and tested, and establishes a new
recorded checkpoint.
## 3. Verify publication
## 3. Publish the reviewed merge
The merge push runs Release Please again, creates the tag and GitHub release,
and publishes npm followed by MCP Registry metadata. Both publishers check
out Release Please's exact release SHA. The triggering workflow also runs
from that release commit so npm's provenance records the actual source.
After the release PR has merged:
```bash
gh workflow run release.yml --ref release/5.0.0 \
-f release_branch=release/5.0.0 -f phase=publish
```
Publication creates the release from the merged bot PR without preparing or
updating another PR. Both npm and MCP Registry jobs check out Release Please's
exact release SHA. They do not build the current main tip or a mutable branch.
The publish dispatch runs from the frozen release branch so npm's provenance
records the actual release commit. The workflow rejects a mismatch between
the tagged release SHA and the dispatch SHA before either registry publish.
Before invoking Release Please, the workflow checks that the release branch
still equals the triggering SHA and rejects main or tag refs. Before either
registry publish, it rejects a mismatch between the tagged release SHA and
the triggering SHA. These checks detect moved branches; maintainers must also
keep the release branch frozen throughout publication.
See [npm's provenance implementation](https://github.com/npm/cli/blob/v11.16.0/workspaces/libnpmpublish/lib/provenance.js)
for the use of GitHub's workflow ref and commit SHA.
@@ -82,7 +78,7 @@ Record these outcomes separately:
A GitHub tag alone does not establish npm or MCP Registry publication.
## 4. Sync metadata back to main
## Sync metadata back to main
After publication, open a PR from the release branch back to main. Preserve
main's later implementation changes and resolve generated-file conflicts by
@@ -101,7 +97,7 @@ publishing it again. Re-run failed jobs in the original publication run so its
release SHA and outputs stay fixed. If only MCP publication failed, retry that
job after checking that the npm canary succeeded.
Do not dispatch a fresh publish phase to repair an already-created release:
Do not start a fresh workflow run to repair an already-created release:
Release Please will not create the same release again. Do not move the tag,
delete the release, or unpublish npm as a retry. A defective public package
requires a reviewed correction and a new version.
@@ -1,10 +1,13 @@
import { execFile } from "node:child_process";
import { readFile } from "node:fs/promises";
import { readFile, writeFile } from "node:fs/promises";
import { delimiter, join } from "node:path";
import { promisify } from "node:util";
import { expect, it } from "vitest";
import { parse } from "yaml";
import { z } from "zod";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
const execFileAsync = promisify(execFile);
const stepSchema = z.object({
name: z.string().optional(),
@@ -37,28 +40,17 @@ async function readReleaseWorkflow() {
);
}
it("requires explicit release preparation or publication instead of main pushes", async () => {
it("prepares and publishes only from frozen release branches", async () => {
const workflow = await readReleaseWorkflow();
expect(Object.keys(workflow.on)).toEqual(["workflow_dispatch"]);
expect(workflow.on.workflow_dispatch).toMatchObject({
inputs: {
release_branch: { required: true, type: "string" },
phase: {
required: true,
type: "choice",
default: "prepare",
options: ["prepare", "publish"],
},
},
});
expect(workflow.on.push).toEqual({ branches: ["release/*"] });
expect(workflow.on).toHaveProperty("workflow_dispatch");
expect(workflow.on.workflow_dispatch).toBeNull();
const release = workflow.jobs["release-please"].steps.find((step) =>
step.uses?.startsWith("googleapis/release-please-action@"),
);
expect(release?.with).toMatchObject({
"target-branch": "${{ inputs.release_branch }}",
"skip-github-release": "${{ inputs.phase == 'prepare' }}",
"skip-github-pull-request": "${{ inputs.phase == 'publish' }}",
});
expect(release?.with?.["target-branch"]).toBe("${{ github.ref_name }}");
expect(release?.with).not.toHaveProperty("skip-github-release");
expect(release?.with).not.toHaveProperty("skip-github-pull-request");
});
it("binds npm and MCP publication to the same immutable release SHA", async () => {
@@ -94,25 +86,26 @@ it
execFileAsync("bash", ["-e", "-o", "pipefail", "-c", command], {
env: {
...process.env,
GITHUB_REF: "refs/heads/main",
GITHUB_REF: `refs/heads/${releaseBranch}`,
RELEASE_BRANCH: releaseBranch,
RELEASE_PHASE: "prepare",
},
}),
).rejects.toMatchObject({
code: 1,
stderr: expect.stringMatching(/release_branch/u),
stderr: expect.stringMatching(/release.*branch/u),
});
},
);
it.skipIf(process.platform === "win32").each([
{ phase: "prepare", ref: "refs/heads/feature/unreviewed-workflow" },
{ phase: "publish", ref: "refs/heads/main" },
{ phase: "publish", ref: "refs/heads/release/another-version" },
])(
"rejects $phase from $ref before contacting GitHub",
async ({ phase, ref }) => {
it
.skipIf(process.platform === "win32")
.each([
"refs/heads/main",
"refs/tags/release/5.0.0",
"refs/heads/release/another-version",
])(
"rejects a ref that does not select the release branch: %s",
async (ref) => {
const workflow = await readReleaseWorkflow();
const command = z
.string()
@@ -127,16 +120,65 @@ it.skipIf(process.platform === "win32").each([
...process.env,
GITHUB_REF: ref,
RELEASE_BRANCH: "release/5.0.0",
RELEASE_PHASE: phase,
},
}),
).rejects.toMatchObject({
code: 1,
stderr: expect.stringContaining(`Run ${phase} from`),
stderr: expect.stringContaining("Select a release/ branch"),
});
},
);
it.skipIf(process.platform === "win32").each([true, false])(
"checks the release branch still matches its triggering commit before tagging (match: %s)",
async (match) => {
const workflow = await readReleaseWorkflow();
const command = z
.string()
.parse(
workflow.jobs["release-please"].steps.find(
(step) => step.name === "Validate release selection",
)?.run,
);
const directory = await createTestTempDirectory("rea-release-selection-");
await writeFile(
join(directory, "gh"),
'#!/bin/sh\nprintf "%s\\n" "$TEST_RELEASE_REF_SHA"\n',
{ mode: 0o755 },
);
const result = execFileAsync(
"bash",
["-e", "-o", "pipefail", "-c", command],
{
env: {
...process.env,
PATH: `${directory}${delimiter}${process.env.PATH ?? ""}`,
GITHUB_REF: "refs/heads/release/5.0.0",
RELEASE_BRANCH: "release/5.0.0",
GITHUB_REPOSITORY: "fixture/fixture",
GITHUB_SHA: "1111111111111111111111111111111111111111",
TEST_RELEASE_REF_SHA: match
? "1111111111111111111111111111111111111111"
: "2222222222222222222222222222222222222222",
},
},
);
if (match) {
await expect(result).resolves.toMatchObject({
stdout: expect.stringContaining("Selected release checkpoint:"),
stderr: "",
});
} else {
await expect(result).rejects.toMatchObject({
code: 1,
stderr: expect.stringContaining(
"release branch moved after this run was triggered",
),
});
}
},
);
it.skipIf(process.platform === "win32").each([true, false])(
"publishes only when the tag and provenance source match (match: %s)",
async (match) => {
@@ -146,7 +188,7 @@ it.skipIf(process.platform === "win32").each([true, false])(
.parse(
workflow.jobs["release-please"].steps.find(
(step) =>
step.name === "Bind publication to the dispatched checkpoint",
step.name === "Bind publication to the triggering checkpoint",
)?.run,
);
const result = execFileAsync(