Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(release): drive checkpoint releases from frozen branches
N0zoM1z0fc58fa1eb01f
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex f5c9635b3..73d0cd748 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -1,24 +1,15 @@name: Releaseon:+ 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: falsejobs:@@ -37,27 +28,22 @@ jobs:shell: bashenv: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+ if [[ "${GITHUB_REF}" != "refs/heads/${RELEASE_BRANCH}" || "${RELEASE_BRANCH}" != release/* ]]; then+ echo "Select a release/ branch; main and tags are not release checkpoints." >&2exit 1fi- 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 ! git check-ref-format "refs/heads/${RELEASE_BRANCH}"; then+ echo "Invalid release branch: ${RELEASE_BRANCH}" >&2exit 1fi- if ! git check-ref-format "refs/heads/${RELEASE_BRANCH}"; then- echo "Invalid release_branch: ${RELEASE_BRANCH}" >&2+ 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." >&2exit 1fi- gh api "repos/${GITHUB_REPOSITORY}/git/ref/heads/${RELEASE_BRANCH}" \- --jq '.object.sha'+ printf 'Selected release checkpoint: %s\n' "${selected_sha}"- uses: googleapis/release-please-action@v4id: 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' }}-- - 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+ target-branch: ${{ github.ref_name }}- - 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: bashenv: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." >&2exit 1fidiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 checklistUse 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. Mainpushes do not update release PRs or publish packages. Both publishers buildthe exact SHA tagged by Release Please.diff --git a/docs/releasing.md b/docs/releasing.mdindex 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 acceptingchanges 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 branchChoose the next version from the unreleased Conventional Commits, includingbreaking changes. Record the full source SHA and create `release/VERSION` at@@ -25,47 +25,43 @@ older checkpoint, backport only the release infrastructure first and recordthat additional commit. Do not merge later implementation changes into therelease 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.-Record the final bot PR head after normalization. Approve GitHub-blocked bot-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.--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. Publish the reviewed merge+## 2. Review and merge the bot PR-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.+Record the final bot PR head after normalization. Approve GitHub-blocked bot+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.++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.++## 3. Verify publication++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.++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 mainAfter publication, open a PR from the release branch back to main. Preservemain'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 itsrelease SHA and outputs stay fixed. If only MCP publication failed, retry thatjob 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 packagerequires a reviewed correction and a new version.diff --git a/tests/boundary/filesystem/releaseWorkflow.test.ts b/tests/boundary/filesystem/releaseWorkflow.test.tsindex 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 @@ itexecFileAsync("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(