fix: address review findings in release automation

- release.yml: use RELEASE_TOKEN PAT for gh release create so the
  release:published event triggers npm-publish (GITHUB_TOKEN events
  don't cascade to other workflows)
- release.yml: checkout merge_commit_sha in tag job instead of ref:main
  to avoid tagging later commits
- release.yml: checkout ref:main in prepare job so dispatching from a
  feature branch doesn't pollute the release PR
- release.yml: constrain preid to type:choice[beta] to match
  npm-publish.yml's tag detection
- release.yml: drop -f on push so re-runs fail loudly instead of
  clobbering manual RELEASES.md edits; drop pr-edit fallback
- release.yml: ensure release label exists before gh pr create
- release.yml: make tag push idempotent for re-runs after partial
  failure
- bump-version.mjs: update workspace dependency ranges so major bumps
  don't leave examples pointing at the old major
- bump-version.mjs: run npm install --package-lock-only so npm ci
  on the release PR doesn't fail on lockfile mismatch
- npm-publish.yml: add npm-tag detection to publish-examples so beta
  example releases don't overwrite latest
- .github/release.yml: use [bot] suffix in author excludes so
  dependabot PRs are actually filtered from release notes
- CONTRIBUTING.md: document RELEASE_TOKEN setup; fix npm run -- syntax

Author: ochafik

.github/release.yml

@@ -4,8 +4,8 @@ changelog:
       - ignore-for-release
       - release
     authors:
-      - github-actions
-      - dependabot
+      - github-actions[bot]
+      - dependabot[bot]
   categories:
     - title: Breaking Changes
       labels:

.github/workflows/npm-publish.yml

@@ -138,8 +138,21 @@ jobs:
       - name: Build example
         run: npm run build --workspace examples/${{ matrix.example }}
 
+      - name: Determine npm tag
+        id: npm-tag
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          if [[ "$VERSION" == *"-beta"* ]]; then
+            echo "tag=--tag beta" >> $GITHUB_OUTPUT
+          elif [[ "${{ github.event.release.target_commitish }}" != "main" ]]; then
+            MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1,2)
+            echo "tag=--tag release-${MAJOR_MINOR}" >> $GITHUB_OUTPUT
+          else
+            echo "tag=" >> $GITHUB_OUTPUT
+          fi
+
       - name: Publish example
-        run: npm publish --workspace examples/${{ matrix.example }} --provenance --access public
+        run: npm publish --workspace examples/${{ matrix.example }} --provenance --access public ${{ steps.npm-tag.outputs.tag }}
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_SECRET }}
 

.github/workflows/release.yml

@@ -9,7 +9,8 @@ on:
         default: patch
       preid:
         description: "Prerelease identifier (only used with bump=prerelease)"
-        required: false
+        type: choice
+        options: [beta]
         default: beta
   pull_request:
     types: [closed]
@@ -30,6 +31,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6
+        with:
+          ref: main
 
       - uses: actions/setup-node@v6
         with:
@@ -50,12 +53,13 @@ jobs:
           git checkout -b "$BRANCH"
           git add -u
           git commit -m "chore: release v$VERSION"
-          git push -f -u origin "$BRANCH"
+          git push -u origin "$BRANCH"
+          gh label create release --color B60205 --description "Release PR" 2>/dev/null || true
           gh pr create \
             --title "chore: release v$VERSION" \
             --body "Bumps all packages to \`$VERSION\`. Add release notes to \`RELEASES.md\` before merging. Merging this PR will automatically tag and create the GitHub Release, which triggers npm-publish." \
             --label release \
-            --base main || gh pr edit "$BRANCH" --title "chore: release v$VERSION"
+            --base main
 
   # When a release PR is merged, tag the commit and create the GitHub Release.
   # This triggers the npm-publish workflow.
@@ -68,9 +72,13 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: main
+          ref: ${{ github.event.pull_request.merge_commit_sha }}
 
       - name: Create tag and release
+        env:
+          # PAT so the `release: published` event triggers npm-publish
+          # (events from GITHUB_TOKEN don't cascade to other workflows)
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
         run: |
           VERSION=$(node -p "require('./package.json').version")
           TAG="v$VERSION"
@@ -79,7 +87,7 @@ jobs:
             exit 0
           fi
           git tag "$TAG"
-          git push origin "$TAG"
+          git push origin "$TAG" || echo "tag already on remote"
           PRERELEASE=""
           [[ "$VERSION" == *-* ]] && PRERELEASE="--prerelease"
           gh release create "$TAG" --title "$TAG" --generate-notes $PRERELEASE

CONTRIBUTING.md

@@ -537,6 +537,11 @@ Before publishing releases, ensure the following are configured:
    - Name it `Release`
    - Add required reviewers or other protection rules as needed
 
+3. **`RELEASE_TOKEN` secret**: The release workflow creates GitHub Releases that must trigger the npm-publish workflow. Events from the default `GITHUB_TOKEN` don't cascade to other workflows, so a separate token is needed.
+   - Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new) scoped to this repository with **Contents: write** permission
+   - Go to Settings > Secrets and variables > Actions > New repository secret
+   - Name: `RELEASE_TOKEN`, value: the PAT
+
 ### Publishing a Release
 
 Releases are automated via the [Release workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/release.yml).
@@ -552,6 +557,7 @@ Releases are automated via the [Release workflow](https://github.com/modelcontex
    - The workflow bumps the version across all packages and opens a PR labeled `release`
    - Add release notes to `RELEASES.md` in the PR
    - Approve and merge the PR
+   - _Note: re-running the workflow for the same version fails if the branch already exists. Delete the `release/vX.Y.Z` branch first if you need to redo the bump._
 
 3. **Done** — merging the PR automatically tags the commit and creates the GitHub Release (with auto-generated notes), which triggers the [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml). Approve the deployment once when prompted.
 
@@ -560,7 +566,7 @@ Releases are automated via the [Release workflow](https://github.com/modelcontex
 You can also bump versions locally:
 
 ```bash
-npm run bump patch   # or minor, major, prerelease --preid=beta
+npm run bump -- patch   # or: minor | major | prerelease --preid=beta
 ```
 
 Then commit, push, and create a GitHub Release manually — the npm-publish workflow triggers on release creation.

scripts/bump-version.mjs

@@ -14,6 +14,7 @@
  */
 
 import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 
 const args = process.argv.slice(2);
 if (!args[0]) {
@@ -28,10 +29,21 @@ const exec = (cmd) =>
     .toString()
     .trim();
 
+const pkgName = JSON.parse(readFileSync("package.json", "utf-8")).name;
+
 const newVersion = exec(
   `npm version ${args.join(" ")} --no-git-tag-version`,
 ).replace(/^v/, "");
 exec(`npm pkg set version=${newVersion} --workspaces`);
 
+// Keep workspace dependency ranges compatible (needed on major bumps)
+const [major, minor] = newVersion.split(".");
+exec(
+  `npm pkg set "dependencies.${pkgName}=^${major}.${minor}.0" --workspaces`,
+);
+
+// Sync package-lock.json so `npm ci` doesn't reject the release PR
+exec("npm install --package-lock-only --ignore-scripts");
+
 console.error(`Bumped root + workspaces to ${newVersion}`);
 console.log(newVersion);