ci: require --tag for releases, route v3 template PRs to 3.x (#16360)

# Overview

Main-side tooling for the v4 beta phase. Harden `pnpm release` against
accidentally publishing to `latest`, route the post-release templates
workflow by release major so v3 patches (published from `3.x`) produce
the right PR on the right branch, and close script-injection patterns in
that workflow.

Companion to the pending `3.x` cutover. No functional changes to Payload
itself.

## Key Changes

- **`tools/releaser/src/release.ts` — require `--tag`; disallow
`latest`**

- Abort when `--tag` is missing. Previously an omitted tag flowed into
`pnpm publish --tag undefined` and published to a literal `undefined`
dist-tag.
- Abort when `--tag latest` is passed. During the v4 beta phase, stable
v4 must publish to `beta` so it cannot displace v3 on `latest`.
- Both guards print a pointer to remove them at Phase 2 when v4 goes
stable.

- **`.github/workflows/post-release-templates.yml` — route by release
tag**

- Compute `target_branch` from the release tag: `v3.*` → `3.x`,
everything else → `main`.
- `update_templates` checks out `target_branch`, so templates are
regenerated from the source that corresponds to the released major.
- PR `base` now targets `target_branch` instead of hardcoded `main`. A
v3 patch produces a templates PR against `3.x`; a v4 release produces
one against `main`.
- `workflow_dispatch` still works; it uses `git describe` to pick the
latest non-v2 tag and routes the same way.

- **`.github/workflows/post-release-templates.yml` — harden release-tag
handling**
- Pass `github.event.release.tag_name` through `env:` rather than
interpolating `${{ … }}` directly into `run:` blocks (closes the classic
GHA script-injection pattern).
- Validate the tag against a semver shape before it fans out into step
outputs and downstream steps; the job aborts on a malformed tag instead
of letting shell-metacharacter content reach the branch name, PR title,
or PR body.
- Replace the remaining inline `${{ … release_tag }}` shell
interpolations with `$RELEASE_TAG` from `env:`.

## Design Decisions

- **Disallow `latest` rather than default to `beta`.** Explicit caller
intent; Phase 2 revert is a two-line deletion. No branch-detection or
magic defaults inside the releaser.
- **Route rather than skip v3 in post-release-templates.** An earlier
iteration skipped v3 events entirely. Routing preserves template
regeneration for 3.x patches, which is the behavior the 3.x maintenance
line needs.
- **Workflow file stays on `main` only.** `release: published` events
run the workflow from the repo default branch regardless, so the file
does not need to exist on `3.x`. It only needs to check out `3.x` when
handling a v3 release.
- **Validate tag shape at the boundary, not everywhere downstream.** A
single semver regex at the `determine_tag` step means all downstream
outputs, branch names, and PR inputs inherit a safe character set
without repeating validation.
- **No changes to `post-release.yml`, `publish-prerelease.yml`,
`main.yml`, `templates.ts`, or docs.** The release-commenter's existing
`tag-filter: 'v\d'` already partitions v3/v4. Nightly canary cron is
disabled in a separate prior commit and is expected to be re-enabled
when v4 dev ramps up.

## Overall Flow

```mermaid
flowchart TD
    A[pnpm release --bump X] --> B{--tag provided?}
    B -- no --> X1[abort]
    B -- yes --> C{tag == latest?}
    C -- yes --> X2[abort]
    C -- no --> D[publish to specified dist-tag]

    R[GitHub release published] --> V{tag matches semver?}
    V -- no --> X3[abort]
    V -- yes --> F{tag starts with v3?}
    F -- yes --> G[checkout 3.x, regen templates, PR base=3.x]
    F -- no --> H[checkout main, regen templates, PR base=main]
```

Author: denolfe

.github/workflows/post-release-templates.yml

@@ -15,6 +15,7 @@ jobs:
     runs-on: ubuntu-24.04
     outputs:
       release_tag: ${{ steps.determine_tag.outputs.release_tag }}
+      target_branch: ${{ steps.determine_tag.outputs.target_branch }}
     steps:
       - name: Checkout
         uses: actions/checkout@v5
@@ -24,23 +25,42 @@ jobs:
 
       - name: Determine Release Tag
         id: determine_tag
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          EVENT_TAG: ${{ github.event.release.tag_name }}
         run: |
-          if [ "${{ github.event_name }}" == "release" ]; then
-            echo "Using tag from release event: ${{ github.event.release.tag_name }}"
-            echo "release_tag=${{ github.event.release.tag_name }}" >> "$GITHUB_OUTPUT"
+          if [ "$EVENT_NAME" == "release" ]; then
+            echo "Using tag from release event: $EVENT_TAG"
+            RELEASE_TAG="$EVENT_TAG"
           else
             # pull latest tag from github, must match any version except v2. Should match v3, v4, v99, etc.
             echo "Fetching latest tag from github..."
-            LATEST_TAG=$(git describe --tags --abbrev=0 --match 'v[0-9]*' --exclude 'v2*')
-            echo "Latest tag: $LATEST_TAG"
-            echo "release_tag=$LATEST_TAG" >> "$GITHUB_OUTPUT"
+            RELEASE_TAG=$(git describe --tags --abbrev=0 --match 'v[0-9]*' --exclude 'v2*')
+            echo "Latest tag: $RELEASE_TAG"
+          fi
+
+          # Validate shape before fanning out into outputs / downstream shell contexts.
+          if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Refusing to proceed: release tag does not match semver: $RELEASE_TAG"
+            exit 1
+          fi
+
+          echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+
+          # Route v3 releases to the 3.x branch; everything else (v4+) to main.
+          if [[ "$RELEASE_TAG" == v3.* ]]; then
+            echo "target_branch=3.x" >> "$GITHUB_OUTPUT"
+          else
+            echo "target_branch=main" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Wait until latest versions resolve on npm registry
+        env:
+          RELEASE_TAG: ${{ steps.determine_tag.outputs.release_tag }}
         run: |
-          ./.github/workflows/wait-until-package-version.sh payload ${{ steps.determine_tag.outputs.release_tag }}
-          ./.github/workflows/wait-until-package-version.sh @payloadcms/translations ${{ steps.determine_tag.outputs.release_tag }}
-          ./.github/workflows/wait-until-package-version.sh @payloadcms/next ${{ steps.determine_tag.outputs.release_tag }}
+          ./.github/workflows/wait-until-package-version.sh payload "$RELEASE_TAG"
+          ./.github/workflows/wait-until-package-version.sh @payloadcms/translations "$RELEASE_TAG"
+          ./.github/workflows/wait-until-package-version.sh @payloadcms/next "$RELEASE_TAG"
 
   update_templates:
     needs: wait_for_release
@@ -51,6 +71,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          ref: ${{ needs.wait_for_release.outputs.target_branch }}
 
       - name: Setup
         uses: ./.github/actions/setup
@@ -85,14 +107,15 @@ jobs:
         id: commit
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ needs.wait_for_release.outputs.release_tag }}
         run: |
           set -ex
           git config --global user.name "github-actions[bot]"
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
           git diff --name-only
 
-          export BRANCH_NAME=templates/bump-${{ needs.wait_for_release.outputs.release_tag }}-$(date +%s)
+          BRANCH_NAME="templates/bump-${RELEASE_TAG}-$(date +%s)"
           echo "branch=$BRANCH_NAME" >> "$GITHUB_OUTPUT"
 
       - name: Create pull request
@@ -103,7 +126,7 @@ jobs:
           author: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
           commit-message: 'templates: bump templates for ${{ needs.wait_for_release.outputs.release_tag }}'
           branch: ${{ steps.commit.outputs.branch }}
-          base: main
+          base: ${{ needs.wait_for_release.outputs.target_branch }}
           assignees: ${{ github.actor }}
           title: 'templates: bump for ${{ needs.wait_for_release.outputs.release_tag }}'
           body: |

package.json

@@ -96,7 +96,7 @@
     "prepare-run-test-against-prod:ci": "rm -rf test/packed && rm -rf test/node_modules && rm -rf app && rm -f test/pnpm-lock.yaml && pnpm run script:pack --all --no-build --dest test/packed && pnpm runts test/setupProd.ts && cd test && pnpm i --ignore-workspace && cd ..",
     "publish-prerelease": "pnpm --filter releaser publish-prerelease",
     "reinstall": "pnpm clean:all && pnpm install",
-    "release": "pnpm --filter releaser release --tag latest",
+    "release": "pnpm --filter releaser release --tag beta",
     "runts": "cross-env NODE_OPTIONS=\"--no-deprecation --no-experimental-strip-types\" node --no-deprecation --no-experimental-strip-types --import @swc-node/register/esm-register",
     "script:audit": "pnpm audit -P",
     "script:audit:critical": "pnpm audit -P --audit-level critical",

tools/releaser/src/release.ts

@@ -1,8 +1,13 @@
 /**
- * Usage: GITHUB_TOKEN=$GITHUB_TOKEN pnpm release --bump <minor|patch>
+ * Usage: GITHUB_TOKEN=$GITHUB_TOKEN pnpm release --bump <prerelease|prepatch|preminor|premajor>
  *
  * Ensure your GITHUB_TOKEN is set in your environment variables
  * and also has the ability to create releases in the repository.
+ *
+ * During the v4 beta phase, this script:
+ *   - must be run from the `main` branch
+ *   - requires a v4.x version in root package.json
+ *   - requires --tag beta (or canary); 'latest' is disallowed
  */
 
 import type { ExecSyncOptions } from 'child_process'
@@ -39,7 +44,7 @@ const {
   'dry-run': dryRun,
   'git-commit': gitCommit = true, // Whether to run git commit operations
   'git-tag': gitTag = true, // Whether to run git tag and commit operations
-  tag, // Tag to publish to: latest, beta, canary
+  tag, // Tag to publish to: beta, canary (latest disallowed during v4 beta phase)
 } = args
 
 const logPrefix = dryRun ? chalk.bold.magenta('[dry-run] >') : ''
@@ -117,6 +122,42 @@ async function main() {
     throw new Error('Could not find version in package.json')
   }
 
+  if (!tag) {
+    abort(
+      `--tag is required. Use --tag beta (or canary). 'latest' is disallowed during v4 beta phase.`,
+    )
+  }
+  if (tag === 'latest') {
+    abort(
+      `'latest' dist-tag is disallowed during the v4 beta phase. Use --tag beta. Remove this guard when v4 goes stable.`,
+    )
+  }
+
+  // v4 beta guards — remove when v4 goes stable
+  const currentBranch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim()
+  if (currentBranch !== 'main') {
+    abort(`Releases must be run from 'main'. Current branch: ${currentBranch}.`)
+  }
+
+  if (!/^4\./.test(monorepoVersion)) {
+    abort(
+      `Expected v4.x release; package.json version is ${monorepoVersion}. This script is pinned to v4 during beta phase.`,
+    )
+  }
+
+  const prerelease = semver.prerelease(monorepoVersion)
+  const prereleaseId = prerelease?.[0]
+  if (!prereleaseId) {
+    abort(
+      `Stable releases are disallowed during v4 beta phase. package.json version (${monorepoVersion}) has no prerelease identifier.`,
+    )
+  }
+  if (prereleaseId !== tag) {
+    abort(
+      `Version/tag mismatch: version ${monorepoVersion} has prerelease '${prereleaseId}' but --tag is '${tag}'. These must match.`,
+    )
+  }
+
   const nextReleaseVersion = semver.inc(monorepoVersion, bump, undefined, tag)
 
   if (!nextReleaseVersion) {
@@ -145,6 +186,7 @@ async function main() {
   let packageDetails = await getPackageDetails(packagePublishList)
 
   console.log(chalk.bold(`\n  Version: ${monorepoVersion} => ${chalk.green(nextReleaseVersion)}\n`))
+  console.log(chalk.bold.yellow(`  Branch: ${currentBranch}`))
   console.log(chalk.bold.yellow(`  Bump: ${bump}`))
   console.log(chalk.bold.yellow(`  Tag: ${tag}\n`))
   console.log(chalk.bold.green(`  Changes (${packageDetails.length} packages):\n`))