npm has introduced a granular access-token permission that lets automation stage a package version without publishing it directly. The staged version remains non-public until a maintainer reviews and approves it with two-factor authentication (2FA).
For teams that publish from CI/CD, the change creates a human checkpoint between an automated upload and public release. It can reduce the impact of a compromised publishing credential, although stage-only tokens still retain some package-management write permissions and should not be treated as read-only credentials.
What changed
Granular npm access tokens can now be configured with Read and write (stage only) permission. A token with this permission cannot directly publish a new package version using npm publish. Instead, the workflow must use npm stage publish.
The staged version is uploaded to npm but is not publicly available. A maintainer can inspect the staged package and then approve or reject it. Approval makes the version public and requires 2FA; rejection permanently removes the staged package and also requires 2FA.
npm’s announcement describes the permission as an opt-in feature. Existing tokens and their direct-publishing capabilities are not changed by the introduction of stage-only tokens.
How the staged workflow works
The automation and review process is separate from a traditional direct publish:
- Create a granular access token on npmjs.com and select Read and write (stage only) for the packages or scopes the workflow needs.
- Configure the release job to use that token and run
npm stage publish. - Review the staged release with the npm CLI or on npmjs.com.
- Approve the stage with 2FA to make it public, or reject it with 2FA to remove it.
The CLI provides several review commands. Maintainers can use npm stage list to see pending stages, npm stage view to inspect stage details, and npm stage download to download a package tarball for review. The same staged packages are available through the Staged Packages tab on npmjs.com.
Approval uses npm stage approve <stage-id>. The CLI can receive the one-time password with --otp <code>. To remove a release instead, maintainers can run npm stage reject <stage-id>.
The npm staged publishing documentation describes the lifecycle, while the npm stage command reference documents the available commands and behavior.
Requirements and availability
Staged publishing is currently intended for existing packages. A brand-new package cannot be staged, and the actor or workflow must have write or publish access to the existing package.
The documented minimum versions are npm CLI 11.15.0 and Node.js 22.14.0. Teams should verify these requirements in every release environment before changing a production pipeline.
Staging itself does not require a 2FA prompt, but the account must have 2FA enabled for a maintainer to approve or reject a staged package. That means the process is not fully unattended from upload through publication: automation can prepare the release, but a maintainer must complete the final decision.
Granular access tokens are created through the npm website rather than the CLI. The token interface supports package or scope restrictions, expiration dates, and optional IP-range restrictions. It can be configured for all accessible packages or for up to 50 selected packages or scopes, according to npm’s token documentation.
What happens to direct publishing
A workflow using a stage-only token cannot simply continue running npm publish. npm rejects that operation with E_STAGE_REQUIRED and directs the user to stage the version instead. A bypass-2FA setting does not convert a stage-only token into a direct-publishing credential.
npm’s documentation also says that direct publishing of new package versions through granular access tokens will be removed in January 2027. This is a future change, not a completed removal. npm has not specified the exact enforcement mechanism, effective date, or exceptions in the supplied documentation.
Teams that depend on direct publishing with granular tokens should therefore plan a migration before that stated timeline, while recognizing that the current stage-only feature is opt-in and does not alter existing tokens automatically.
Security boundaries to keep in mind
The main benefit is the additional approval checkpoint. A compromised stage-only credential cannot directly make a new package version public through npm publish. Instead, the credential can upload a non-public stage that still requires maintainer approval.
That boundary is limited. Stage-only tokens retain other write capabilities, including deprecating package versions and moving dist-tags. npm explicitly does not describe staged publishing as a general-purpose security boundary, so these tokens should still be protected like other write credentials. Organizations should review whether the workflow needs those retained permissions and restrict the token to only the packages or scopes it requires.
Staged publishing also does not replace review procedures. Maintainers remain responsible for inspecting the contents and deciding whether to approve the release. Multiple staged versions can be pending at the same time, and normal publishing can continue while stages await review.
Details that can affect release design
A staged version shares the package’s semver uniqueness index, so teams should account for version uniqueness when preparing retries or parallel releases. The package tag is fixed when the version is staged. If the tag needs to change, the documented process is to reject the stage and stage the package again with the desired tag.
The supplied documentation describes staged workflows for scoped public packages and notes that staging respects private: true, but it does not establish behavior for every private-package, organization-policy, or non-public-registry arrangement. Teams with those configurations should confirm compatibility before adopting the workflow broadly.
What you should do
- Inventory CI/CD workflows that use npm tokens to publish package versions directly.
- Upgrade release environments to npm CLI 11.15.0 or later and Node.js 22.14.0 or later.
- Create a narrowly scoped granular token on npmjs.com with the stage-only permission.
- Replace
npm publishwithnpm stage publishin the relevant workflow. - Test the complete lifecycle, including staging, inspection, approval, and rejection.
- Document who reviews staged packages and ensure an approver can complete the 2FA step.
- Review the token’s remaining dist-tag and deprecation permissions and limit package access where possible.
- Plan for npm’s stated January 2027 removal of direct granular-token publishing, while watching for the final enforcement details.
Trusted publishing is a separate OIDC-based option. npm documents that it can be used with staged publishing, but staged packages still require maintainer review and 2FA before becoming public. Teams evaluating alternatives to long-lived tokens should assess that path separately from the stage-only token workflow.
