fix(release): publish from explicit source checkpoints (#1006)

* fix(release): publish from explicit source checkpoints

Dispatch preparation and publication against a frozen release branch.
Bind package builds and provenance to the same tagged commit, enable
release-branch PR CI, and document the maintainer workflow.

Assisted-by: Sakuya (gensokyo-skills:sakuya-checkpointed-execution)

* fix(release): stop publication when the checkpoint has moved

Reject unknown phases and a release-branch tip that differs from the
dispatch SHA before Release Please creates a tag. Keep registry jobs and
catalog pushes on their own phase, and run website checks for release PRs.

* fix(release): require a token that can trigger release CI

Stop falling back to GITHUB_TOKEN, which cannot start workflow runs for the release pull request it creates.

* test(release): require the CI-capable release token

Lock the workflow to RELEASE_PLEASE_TOKEN and fail preparation when that secret is missing.

* style(release): format the release-token test

---------

Co-authored-by: N0zoM1z0 <1705004398@qq.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>

.github/workflows/release.yml

@@ -1,15 +1,24 @@
 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-${{ github.ref }}
+  group: release-${{ inputs.release_branch }}
   cancel-in-progress: false
 
 jobs:
@@ -21,77 +30,125 @@ jobs:
       pull-requests: write
     outputs:
       release_created: ${{ steps.release.outputs.release_created }}
-      tag_name: ${{ steps.release.outputs.tag_name }}
       sha: ${{ steps.release.outputs.sha }}
     steps:
+      - name: Require a CI-capable release token
+        shell: bash
+        env:
+          RELEASE_PLEASE_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+        run: |
+          if [[ -z "${RELEASE_PLEASE_TOKEN}" ]]; then
+            echo "RELEASE_PLEASE_TOKEN is required. Pull requests and catalog commits created with GITHUB_TOKEN do not start workflow runs, so the normalized release head would have no CI result to approve." >&2
+            exit 1
+          fi
+
       - name: Validate release selection
         shell: bash
         env:
-          GH_TOKEN: ${{ github.token }}
-          RELEASE_BRANCH: ${{ github.ref_name }}
+          RELEASE_BRANCH: ${{ inputs.release_branch }}
+          RELEASE_PHASE: ${{ inputs.phase }}
         run: |
-          if [[ "${GITHUB_REF}" != "refs/heads/${RELEASE_BRANCH}" || "${RELEASE_BRANCH}" != release/* ]]; then
-            echo "Select a release/ branch; main and tags are not release checkpoints." >&2
+          if [[ "${RELEASE_PHASE}" != prepare && "${RELEASE_PHASE}" != publish ]]; then
+            echo "phase must be prepare or publish." >&2
+            exit 1
+          fi
+          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
             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
-          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
+
+      - name: Resolve release branch tip
+        id: branch
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_BRANCH: ${{ inputs.release_branch }}
+        run: |
+          sha="$(gh api "repos/${GITHUB_REPOSITORY}/git/ref/heads/${RELEASE_BRANCH}" --jq '.object | select(.type == "commit") | .sha')"
+          if [[ ! "${sha}" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "The release branch tip is not a commit." >&2
+            exit 1
+          fi
+          echo "sha=${sha}" >> "${GITHUB_OUTPUT}"
+
+      - name: Require the publish dispatch to match the branch tip
+        if: inputs.phase == 'publish'
+        shell: bash
+        env:
+          BRANCH_SHA: ${{ steps.branch.outputs.sha }}
+        run: |
+          if [[ "${BRANCH_SHA}" != "${GITHUB_SHA}" ]]; then
+            echo "The release branch tip differs from the dispatched checkpoint; refusing to create a release for a moved source." >&2
             exit 1
           fi
-          printf 'Selected release checkpoint: %s\n' "${selected_sha}"
 
       - uses: googleapis/release-please-action@v4
         id: release
         with:
-          # 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: ${{ github.ref_name }}
+          # A dedicated credential lets release-PR updates trigger CI.
+          # GITHUB_TOKEN-authored pull requests do not start workflow runs.
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          target-branch: ${{ inputs.release_branch }}
+          skip-github-release: ${{ inputs.phase == 'prepare' }}
+          skip-github-pull-request: ${{ inputs.phase == 'publish' }}
 
-      - name: Bind publication to the triggering checkpoint
-        if: steps.release.outputs.release_created == 'true'
+      - 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'
         shell: bash
         env:
           RELEASE_SHA: ${{ steps.release.outputs.sha }}
         run: |
           if [[ "${RELEASE_SHA}" != "${GITHUB_SHA}" ]]; then
-            echo "The tagged release SHA differs from the triggering checkpoint; refusing to publish mismatched source provenance." >&2
+            echo "The tagged release SHA differs from the dispatched checkpoint; refusing to publish mismatched source provenance. The GitHub release already exists; do not dispatch publish again." >&2
             exit 1
           fi
 
       - name: Check out release pull request
-        if: steps.release.outputs.prs_created == 'true'
+        if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'
         uses: actions/checkout@v6
         with:
           ref: ${{ fromJSON(steps.release.outputs.pr).headBranchName }}
           persist-credentials: false
 
       - name: Set up Node.js for generated documentation
-        if: steps.release.outputs.prs_created == 'true'
+        if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'
         uses: actions/setup-node@v6
         with:
           node-version-file: .nvmrc
           package-manager-cache: false
 
       - name: Install dependencies
-        if: steps.release.outputs.prs_created == 'true'
+        if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'
         run: npm ci
 
       - name: Regenerate release documentation
-        if: steps.release.outputs.prs_created == 'true'
+        if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'
         run: npm run docs:generate
 
       - name: Commit canonical release catalog
-        if: steps.release.outputs.prs_created == 'true'
+        if: inputs.phase == 'prepare' && steps.release.outputs.prs_created == 'true'
         shell: bash
         env:
           # Use the same identity for the follow-up commit so it also triggers CI.
-          GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.RELEASE_PLEASE_TOKEN }}
           RELEASE_PR_JSON: ${{ steps.release.outputs.pr }}
         run: |
           release_pr_branch="$(node --input-type=module -e '
@@ -127,7 +184,7 @@ jobs:
   publish:
     name: Publish to npm
     needs: release-please
-    if: needs.release-please.outputs.release_created == 'true'
+    if: inputs.phase == 'publish' && needs.release-please.outputs.release_created == 'true'
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -198,7 +255,7 @@ jobs:
   publish-mcp:
     name: Publish to MCP Registry
     needs: [release-please, publish]
-    if: needs.release-please.outputs.release_created == 'true' && needs.publish.result == 'success'
+    if: inputs.phase == 'publish' && needs.release-please.outputs.release_created == 'true' && needs.publish.result == 'success'
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/website-check.yml

@@ -2,7 +2,7 @@ name: Website checks
 
 on:
   pull_request:
-    branches: [main]
+    branches: [main, "release/*"]
     paths:
       - "website/**"
       - "scripts/verify-website.py"