Release: Harden npm package release paths - #79859

ciampo · 2026-07-03T21:41:21Z

What?

Follow-up to the Gutenberg 23.5 npm package release failure.

This PR makes every workflow-dispatched npm package release path (latest, development/next, bugfix, and wp) push Git metadata in explicit phases after npm publication succeeds.

Why?

The previous Git push behavior coupled release branch updates with package tag publication. When that late push failed, npm had already been changed and the workflow did not print exact recovery commands. The same failure mode existed outside the original npm-latest path, so all npm release types now use the same hardened implementation.

Note

This PR intentionally hardens the existing npm package release procedure. It keeps the current release conventions in place: packages are still published through Lerna, release metadata is still pushed back to the existing npm release branches, and per-package Git tags are still produced. Bigger process decisions, such as whether those package tags are still needed, are follow-ups.

How?

Create Lerna version commits and package tags locally with --no-push for latest, next, bugfix, and CLI-driven wp releases.
Publish npm packages with lerna publish from-package after preflight checks.
Add an explicit --resume mode for partial-publish recovery from an existing local version commit and package tags.
Require --resume runs to have local package version tags at HEAD before doing npm work.
Keep fresh-publish preflight strict: target npm versions must be absent.
Let resume preflight continue when expected versions already exist, but fail on mismatched versions or wrong dist-tags.
Compare npm registry versions without SemVer build metadata, matching npm's published version behavior for next releases.
Treat npm whoami as the hard credential gate and keep npm access list packages as a warning-only diagnostic.
Preserve local version metadata during retry/recovery instead of resetting it away after a partial publish.
Print explicit resume guidance when npm publication still fails after retry, so releasers do not start a fresh release after possible partial publication.
Push and verify the npm release branch by expected publish commit SHA using exact refs/heads/... refs.
Push only the package tags created for the current release using fully qualified tag refspecs.
Verify remote package tags peel to the publish commit.
Print copy-pasteable branch/tag recovery commands when npm publication succeeds but Git metadata publication fails.
Route the workflow wp dispatch through release-cli npm-wp instead of inline raw Lerna.
Scope package release workflow concurrency by target npm release branch, so latest and bugfix serialize on wp/latest.

TODO / Follow-ups

The npm package-version preflight intentionally checks target versions sequentially in this PR. A bounded-concurrency pass could reduce release latency for full releases, but it is deferred so the first hardening change keeps npm registry errors ordered and easy to diagnose.

Testing Instructions

npm run test:unit -- tools/release/commands/test/packages.js
npm run lint:js -- tools/release/cli.js tools/release/commands/packages.js tools/release/commands/test/packages.js
Confirm the latest, development/next, bugfix, and wp release paths all use local lerna version ... --no-push, lerna publish from-package, and the shared metadata push/recovery flow.
Confirm --resume skips versioning, requires local package tags at HEAD, and allows already-published expected versions only when the expected dist-tag points at that version.
Confirm npm access-list failures warn but do not abort after npm whoami succeeds, and failed publish retries print resume guidance.

Testing Instructions for Keyboard

N/A

Screenshots or screencast

N/A

Use of AI Tools

This PR was prepared with assistance from OpenAI Codex.

github-actions · 2026-07-03T21:56:52Z

Size Change: +290 B (0%)

Total Size: 7.67 MB

📦 View Changed

Filename	Size	Change
`build/scripts/block-library/index.min.js`	332 kB	+290 B (+0.09%)

_{compressed-size-action}

github-actions · 2026-07-06T06:50:52Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

tyxla

Wow, there's a lot going on here 😅

Have we had a chance to test this on a fork or something?

tyxla · 2026-07-06T08:02:38Z

-					stdio: 'inherit',
-				}
+			log(
+				`>> Do not start a fresh release. After checking npm registry state, rerun the same release command from this checkout with --resume --repository-path ${ gitWorkingDirectoryPath }.`


For next releases, Lerna writes build metadata (+<sha>) into both package.json and the git tag, so version in getNpmReleasePackages will be ...-next.v.202607060000+abc123. On --resume that version is already published, but npm strips build metadata on publish, so npm view pkg@…+abc123 version --json returns the stripped ...202607060000. The check registryVersion !== version (and the identical dist-tag check) is therefore always true and will throw an error. --resume is suggested for npm-next, but it looks like it can never succeed in that scenario.

Addressed with the help of an AI agent.

The comparison now happens against the npm registry version form by stripping SemVer build metadata from the local package version before checking the registry version and dist-tag. This keeps next recovery compatible with versions like 4.50.0-next.v.202607060000+sha, while still failing if the registry returns a different version or the expected dist-tag points elsewhere.

tyxla · 2026-07-06T08:06:37Z

                    - latest
                    - bugfix


getConfig('bugfix') and getConfig('latest') both resolve to npmReleaseBranch='wp/latest' / distTag='latest'. So a bugfix and a latest can run simultaneously since both check out wp/latest, both run lerna version patch --no-push and lerna publish from-package --dist-tag latest, and both push to origin/wp/latest, which may result in push failures or conflicting version bumps.

I didn't think of that, it's true.

The workflow concurrency key is now scoped by "target npm release branch" instead of raw release type. latest and bugfix both serialize on wp/latest, development serializes on wp/next, and wp releases remain scoped by their WordPress version branch.

tyxla · 2026-07-06T08:11:34Z

+	return [
+		'Push and verify the release branch:',
+		`git push origin "${ publishCommit }:refs/heads/${ npmReleaseBranch }"`,
+		`git ls-remote --heads origin "${ npmReleaseBranch }"`,


git ls-remote --heads origin wp/latest matches by ref tail, so a sibling ref such as refs/heads/backport/wp/latest also matches and because it is earlier in sorting, is emitted first. If that happens verifyRemoteNpmReleaseBranch will compare the wrong commit and throw a false error after npm already published, failing the release. Should we match the exact refs/heads/<branch> ref instead of trusting the first line?

Yeah, true.

I updated the branch verification to use the exact refs/heads/<branch> ref in git ls-remote, and the parser only accepts a line whose ref name exactly matches that branch. The printed recovery command uses the same exact ref form.

tyxla · 2026-07-06T08:19:00Z

 	}

 	const temporaryFolders = [];
+	if ( config.resume && ! config.gitWorkingDirectoryPath ) {


We're only validating the repository path, and nothing else. Is there a possibility that a prior run died earlier, so we're on the wrong HEAD? Should we add a check for that as well?

Addressed.

publishVersionedPackagesToNpm() now fails before any npm work when --resume finds no release package tags at HEAD.

That keeps resume tied to an existing local version/tag state instead of allowing a plain checkout path to enter the recovery flow.

tyxla · 2026-07-06T08:20:11Z

+	try {
+		await runPhase( 'Release branch push', async () => {
+			log( '>> Pushing release branch to remote.' );
+			await git.raw(


getTagPushCommands and getNpmReleaseGitRecoveryCommands build the printed recovery commands, while pushNpmReleaseGitMetadata builds the real push independently.

Should we unify and use the same underlying tooling?

Yes, that's a good opportunity for unification.

Branch pushes and printed recovery commands now both use the same getBranchRefspec() helper, so the real push path and copy-paste recovery path stay aligned.

ciampo · 2026-07-06T15:02:28Z

Wow, there's a lot going on here 😅

Yes, the PR grew in size progressively as I worked on it, and it received feedback.

I'm actually going to break it down into 3 smaller PRs, for ease of review:

Have we had a chance to test this on a fork or something?

Not personally. Ideally we'd have some fork and / or sandboxed registry of sorts, but I'm not aware of any. Maybe @desrosj has better knowledge here?

release: Harden npm metadata publishing

b66d909

ciampo requested a review from Copilot July 3, 2026 21:42

Copilot started reviewing on behalf of ciampo July 3, 2026 21:42 View session

ciampo self-assigned this Jul 3, 2026

This comment was marked as resolved.

Sign in to view

release: Stabilize npm release concurrency key

f54b46e

ciampo added 2 commits July 3, 2026 23:58

release: Cover npm metadata publishing helpers

4b47221

release: Document npm preflight concurrency follow-up

282c0d3

ciampo added [Type] Enhancement A suggestion for improvement. Gutenberg Plugin Issues or PRs related to Gutenberg Plugin management related efforts labels Jul 3, 2026

Release: Harden all npm package publish paths

1a93977

ciampo changed the title ~~Release: Harden npm metadata publishing~~ Release: Harden npm package release paths Jul 3, 2026

Release: Clarify npm wp runtime assumptions

504094c

ciampo requested a review from Copilot July 3, 2026 23:50

Copilot started reviewing on behalf of ciampo July 3, 2026 23:50 View session

This comment was marked as resolved.

Sign in to view

ramonjd reviewed Jul 6, 2026

View reviewed changes

Comment thread tools/release/commands/packages.js Outdated

ramonjd reviewed Jul 6, 2026

View reviewed changes

Comment thread tools/release/commands/packages.js Outdated

ciampo added 2 commits July 6, 2026 08:11

Release: Add npm publish resume preflight

c27acb2

Release: Improve npm publish recovery guidance

90da7fa

ciampo requested a review from ramonjd July 6, 2026 06:24

ciampo marked this pull request as ready for review July 6, 2026 06:45

ciampo requested review from desrosj and manzoorwanijk as code owners July 6, 2026 06:45

ciampo requested review from aduth, gziolo, jsnajdr, tyxla and youknowriad July 6, 2026 06:45

ciampo requested review from Mamaduka and t-hamano July 6, 2026 06:46

ciampo mentioned this pull request Jul 6, 2026

Docs: Clarify release recovery steps #79884

Merged

ciampo requested a review from simison July 6, 2026 07:31

tyxla reviewed Jul 6, 2026

View reviewed changes

bgrgicak mentioned this pull request Jul 6, 2026

Gutenberg 23.5 release checklist #79464

Closed

46 tasks

Release: Address npm release follow-up checks

b9bb977

This was referenced Jul 6, 2026

Release: Harden latest npm metadata publishing #79904

Merged

Release: Harden all npm package release paths #79905

Merged

Release: Run npm phases in separate jobs #79906

Closed

ciampo closed this Jul 6, 2026

t-hamano deleted the codex/harden-npm-release-push branch July 7, 2026 11:16

Uh oh!

Conversation

ciampo commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

TODO / Follow-ups

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Use of AI Tools

Uh oh!

This comment was marked as resolved.

Uh oh!

github-actions Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tyxla left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ciampo commented Jul 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ciampo commented Jul 3, 2026 •

edited

Loading

github-actions Bot commented Jul 3, 2026 •

edited

Loading

github-actions Bot commented Jul 6, 2026 •

edited

Loading