ci: bump templates to the released version on every release

[GermanJablo]

Why

Templates are no longer bumped after releases. It was turned off in #18643 because the workflow waits for npm latest, which still points at v3, so every v4 beta run timed out.

The six non-workspace templates on main already have v4 code but still pin 3.82.1. For example, with-postgres depends on @payloadcms/transformer-sharp@3.82.1, which doesn't exist on npm, so cloning it directly fails to install. create-payload-app@beta hides this because it rewrites the versions.

The bump PRs were also opened with a personal token, and none of the last 12 got merged.

What

• The workflow waits for and pins the exact released version (--payload-version), and the release trigger is back on. The wait is now 10 minutes, since npm scans packages before they resolve.
• The PR is opened with the release App instead of the personal token, and auto-merge is enabled on it.
• The App token only exists in a small open_pr job. The job that installs dependencies and generates the templates has no write access and hands over a patch, which open_pr refuses if it touches anything outside templates/.

Setup needed (repo settings)

• templates environment: allow tags v* (release events run on the tag, which the bump environment doesn't allow) and branch main (manual dispatch). Add RELEASE_APP_CLIENT_ID and RELEASE_APP_PRIVATE_KEY.
• Auto-merge: turn on "Allow auto-merge". If main requires an approval, the PR waits for one unless the App can bypass it.
• After this lands, delete the GH_TOKEN_POST_RELEASE_TEMPLATES secret.

Not covered

• v3 releases: release events run this workflow from the tagged commit, and 3.x no longer has the file (#16358). It needs a copy on 3.x, as #16748 did for post-release.
• Earlier failures: update_templates also failed on every release from v3.81.0 to v3.84.0. The logs have expired, so the cause is unknown. Worth watching on the first run.

Related: PYLD-4162

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: payloadcms/payload/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: cd716885-d862-4d6b-b54a-c525f6915cfa

📥 Commits

Reviewing files that changed from the base of the PR and between da16646 and 4afd451.

📒 Files selected for processing: 2

• .github/workflows/post-release-templates.yml
• .github/workflows/wait-until-package-version.sh

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

The release workflow now runs for published releases. It waits for the requested npm version, generates template changes using the release version, and opens a pull request when changes are present.

Changes: Release template generation and pull requests

Layer / File(s)	Summary
Resolve and use one Payload version tools/scripts/src/generate-template-variations.ts	The generator accepts an optional --payload-version. If omitted, it resolves the latest Payload version once. It uses that version for non-workspace packages and plugin template updates.
Generate and save release template changes .github/workflows/post-release-templates.yml, .github/workflows/wait-until-package-version.sh	The workflow runs for published releases, waits up to 600 seconds for the requested npm version, and passes the release version without its leading v to the generator. It saves generated changes as a patch artifact when changes exist.
Apply patch and open pull request .github/workflows/post-release-templates.yml	A separate job applies the patch only when changed paths are under templates/. It creates a pull request with a GitHub App token and enables squash auto-merge when a pull request number is returned.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant GitHubRelease
  participant PostReleaseTemplatesWorkflow
  participant NpmRegistry
  participant TemplateGenerator
  participant PatchArtifact
  participant OpenPullRequestJob
  GitHubRelease->>PostReleaseTemplatesWorkflow: published release
  PostReleaseTemplatesWorkflow->>NpmRegistry: query requested package version
  NpmRegistry-->>PostReleaseTemplatesWorkflow: return version
  PostReleaseTemplatesWorkflow->>TemplateGenerator: pass release version
  TemplateGenerator-->>PostReleaseTemplatesWorkflow: generate template changes
  PostReleaseTemplatesWorkflow->>PatchArtifact: upload patch when changes exist
  PatchArtifact->>OpenPullRequestJob: provide patch
  OpenPullRequestJob->>OpenPullRequestJob: apply patch and create pull request

Loading

Suggested reviewers: denolfe

Merge Risk: ⚪ Minimal · up to 4afd4

The release workflow is ready to merge after normal checks. The inspected generation path does not appear to block template pull requests.

Security architecture risk: 🔵 Low · up to 4afd4

The separation reduces credentials available during template generation. The remaining risk is bounded mainly to template publication: delayed older releases can propose dependency downgrades, while the protections governing credentials and automatic merging still need confirmation.

Retained concerns

• Low · reliability · inferred: A delayed or replayed older release can start generation after a newer template bump has merged, replace non-workspace dependency pins with its older exact version, and submit that downgrade with automatic merging requested. There is no supersession check. Patch conflict detection only protects against intervening incompatible changes; it does not detect a downgrade generated from the current branch. This can reverse dependency roll-forward, although no downgrade to a known-vulnerable version was demonstrated and final merging depends on repository policy.

Security review details

Security Blast Radius

• inferred — The intended write surface is template content in the selected repository branch, published through pull requests. Changed dependency pins, generated code, and initial migration files can be inherited by projects created from those templates. The visible workflow does not establish access to production tenant databases.

Security Findings and Attack Paths

• inferred — The supported concern is unintended dependency rollback through an older authorized release run, not a demonstrated external attacker exploit. An ordinary pull-request event is not a trigger. Patch-path validation constrains publication location but does not establish dependency freshness or content safety.

Trust Boundaries and Controls

• observed — Release metadata crosses into shell processing through environment variables and is shape-validated before downstream outputs. Generated changes cross into the App-authorized job as a patch, with a template-path check before application. The job's contents: read setting governs its workflow token, not the separately minted App token; effective App permissions and environment protection rules are not shown in these files.

Resilience and Maintainability Implications

• inferred — Fresh target-branch checkout and patch application can reject intervening conflicting changes, providing useful failure containment. They do not enforce release ordering when an older run generates from an already-updated branch. Automatic merging remains dependent on repository rules that were unavailable for inspection.

Hardening Proposals

• proposed — Reject superseded release versions before generation and recheck freshness before merging. Use a stable release-specific publication identity for retries. Separately confirm that the templates environment, App permissions, and branch rules enforce the intended publication authority.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: updating templates to the released version for every release.
Description check		The description directly explains the workflow changes, exact version pinning, release trigger, token handling, auto-merge, setup requirements, and known limitations.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 2 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Git: CodeRabbit could not clone the repository, so clone-backed analysis was skipped and this review may be incomplete. Verify repository clone access, such as SSH credentials, before requesting another full review. If clone access is intentionally unavailable, use path_filters to narrow the review scope.

_{Comment @coderabbitai help to get the list of available commands.}

[denolfe]

This should be updated to use our new payload creds that are used for the release-bump, reference that. Previously, it was using a token attached to a specific github user, which you can see from previous bump PRs.

Ideally, this PR somehow gets automerged as well.

[denolfe]

We should bump this to 8 or 10 mins. Npmjs now does package scanning which can prolong the period between publish and resolving on the registry.