From fc58fa1eb01fe5a8200a78e9551799c9c1a3d256 Mon Sep 17 00:00:00 2001 From: N0zoM1z0 <1705004398@qq.com> Date: Wed, 7 Oct 2026 17:01:04 +0000 Subject: [PATCH] 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) --- .github/workflows/release.yml | 56 +++------ CONTRIBUTING.md | 6 +- docs/releasing.md | 70 ++++++------ .../filesystem/releaseWorkflow.test.ts | 106 ++++++++++++------ 4 files changed, 127 insertions(+), 111 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f5c9635b3..73d0cd748 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70713b30a..796b7cf22 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/docs/releasing.md b/docs/releasing.md index 9db7918ba..fe453323c 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -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. diff --git a/tests/boundary/filesystem/releaseWorkflow.test.ts b/tests/boundary/filesystem/releaseWorkflow.test.ts index 58163cb23..177514cef 100644 --- a/tests/boundary/filesystem/releaseWorkflow.test.ts +++ b/tests/boundary/filesystem/releaseWorkflow.test.ts @@ -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(