ci: publish to npm with trusted publishing and automate the release

[robdecker]

This pull request is for: (mark with an "x")

• examples/*
• modules/next
• packages/next-drupal
• starters/basic-starter
• starters/graphql-starter
• starters/pages-starter
• Other

GitHub Issue: n/a

• I need help adding tests. (mark with an "x")

Describe your changes

Automates releases and moves publishing off a stored npm token.

Why

The release process in MAINTAINING.md no longer works. Three things broke, and because nothing had been released in a while, none of them surfaced until someone tried:

1. lerna version commits straight to main, which now requires a pull request and a review, so the documented git push is rejected.
2. yarn publish prompts for a two-factor code when the account has 2FA enabled. CI has no terminal, so it fails with Can't answer a question unless a user TTY.
3. The publishing token had a short expiry and lapsed. Nothing published in the meantime, so it went unnoticed until npm rejected a publish.

This is also the direction npm is moving. Per GitHub's npm supply chain roadmap: classic tokens are being deprecated, granular tokens with publish rights are being cut to a 7-day lifetime, and the option to bypass 2FA for local publishing is being removed. Both halves of the old process are going away, so this is not worth fixing in place.

Versioning: release-please

release-please reads the conventional commits already enforced by commitlint and keeps a release pull request open with the version bump and changelog. Merging it tags the release and triggers publishing.

The point is that the release commit arrives as a normal pull request, so branch protection is satisfied the ordinary way. Nothing needs to bypass or relax a protection rule.

Tag format is configured to keep continuity with the existing Lerna tags (next-drupal@2.1.0, not next-drupal-v2.1.0), and the manifest starts at the currently published 2.0.1. Prereleases, which the removed Lerna steps used to handle, are now documented via a Release-As: footer.

Lerna stays for running workspace scripts. Only its publish configuration is removed, since it no longer publishes.

Publishing: npm trusted publishing

release.yml publishes with an OIDC credential minted per workflow run and scoped to this repository and workflow filename. Nothing is stored, and it cannot be replayed elsewhere. Provenance attestations are generated automatically because the repository and package are both public.

release-pr.yml keeps publishing experimental versions from a labelled pull request, on the same OIDC path: yarn publish replaced with npm publish, the token reference removed, Node moved to 24. Its same-repo guard is unchanged, so forks still cannot publish.

Both publish jobs assert npm is at least 11.5.1 rather than installing a newer npm, so nothing unpinned is fetched into a job holding id-token: write. Every current Node 24 release already ships npm 11.19.0.

The one credential this adds, and why

This does not leave the repository credential-free. It trades a long-lived npm token for a long-lived GitHub App private key, stored as RELEASE_APP_PRIVATE_KEY. That is worth reviewing rather than glossing over.

release-please cannot open its pull request with the default GITHUB_TOKEN, because this repository does not allow GitHub Actions to create pull requests. There are two ways to fix that:

• Turn that repository setting on. One checkbox, no new secret. But it is a single switch that also grants approval, so every workflow in the repository would gain the ability to approve pull requests, which weakens the review requirement on main.
• Use a GitHub App installation token scoped to this repository. Adds a secret, but the token it mints is short-lived, the permissions are narrow, and no workflow gains approval rights.

This takes the second, on the grounds that a review requirement which automation can satisfy is not much of a requirement. The App private key is the one long-lived secret in the release path, it can be rotated without a publishing outage, and it is owned by the organization rather than an individual.

Note that release-please's own README recommends a personal access token here, not an App token. A PAT would work, but it belongs to a person and carries broader scope. GitHub's own Triggering a workflow docs name both an App installation token and a PAT as the options, so this is a deliberate choice between two supported paths rather than a workaround.

The App is created under the chapter-three organization rather than a personal account, so it does not depend on one person's account remaining active.

Both third-party actions are pinned to full commit SHAs.

This change is inert until it is configured

Merging this enables nothing by itself. Three things must exist first, and they are deliberately not in the diff:

1. A GitHub App owned by the chapter-three org, installed on this repository, with its ID and private key set as repository secrets.
2. An npm trusted publisher entry for release.yml with no environment.
3. An npm trusted publisher entry for release-pr.yml with environment Preview.

All of it is written up under "First-time setup" in MAINTAINING.md rather than left in this description, so it survives the merge.

One detail there is easy to get wrong and worth calling out: the App needs Issues read and write as well as Contents and Pull requests. release-please applies its autorelease labels through the issues API, so without it a release tags and then fails partway.

Not verified by CI

The publish path cannot be exercised before merge, because OIDC only works once npm trusts a workflow on the default branch. First real proof will be the 2.1.0 release. Specifically unverified: whether npm accepts an OIDC credential from a pull_request event when the job declares environment: Preview, and whether release-please picks up e56c636 as the 2.1.0 trigger.

The workflows parse, permissions are scoped per job, both action SHAs match the tags named beside them, and the npm version comparison was checked against both a passing and a failing version. That is the limit of what has been checked here.

References

Publishing:

• npm: Trusted publishing — the setup this implements, including the npm 11.5.1 floor and automatic provenance
• GitHub: Our plan for a more secure npm supply chain — why token publishing is going away
• npm: Multiple trusted publishing configurations — why two entries are allowed

Why the App token is needed:

• GitHub: Managing GitHub Actions settings for a repository — the "Allow GitHub Actions to create and approve pull requests" setting
• GitHub: Prevent GitHub Actions from creating and approving pull requests — confirms it is one switch covering both create and approve
• GitHub: Triggering a workflow — GITHUB_TOKEN events generally do not start new workflow runs, and a pull request it authors produces runs held in an approval-required state; names App installation tokens and PATs as the alternatives
• actions/create-github-app-token — the action used to mint it

Tooling:

• release-please and its action

• Lerna: OIDC trusted publishing — background on why Lerna 8 could not do this

• Was AI used in this pull request?

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
next-drupal-next	Ready	Preview	Sep 22, 2026 7:09pm UTC

2 Skipped Deployments

Project	Deployment	Actions	Updated
next-drupal	Ignored		Sep 22, 2026 7:09pm UTC
next-drupal-v1-6	Ignored		Sep 22, 2026 7:09pm UTC