TechAtelier
DEVELOPMENT · SUPPLY CHAIN

npm stage-only: why your CI should no longer publish alone

Since September 18, 2026, npm offers tokens that can prepare a new package version without being allowed to publish it directly. CI automates the work; a maintainer keeps the final decision with 2FA approval.

A stolen CI secret should not be enough to publish a malicious package version. That is the boundary npm strengthens with new stage-only tokens: automation can submit a release for review, but cannot make it installable by users.

What a stage-only token changes

A granular token can now receive Read and write (stage only) permission. The workflow runs npm stage publish instead of npm publish. The version enters staging, then a maintainer reviews and approves it with two-factor authentication before publication.

If CI attempts a direct npm publish with that token, npm rejects it. Compromising the token therefore no longer provides, by itself, the ability to release a new package version.

The pipeline prepares; it is not the final authority

CI/CD pipelines are excellent at reproducible work: tests, builds, artifacts and release preparation. They become more dangerous when a long-lived secret also gives them irreversible authority.

Stage-only separates those responsibilities: the machine prepares a reproducible version; an authorized person validates production publication.

Stage-only does not make the token harmless

npm notes that the token keeps other package write capabilities, including moving dist-tags and deprecating versions. It must still be protected like any write credential.

Can the npm secret be removed entirely?

Where supported, trusted publishing is the better target: CI authenticates to npm through OIDC and receives short-lived credentials on demand instead of storing a long-lived npm token.

Trusted publishing can also be combined with staged publishing: the workflow authenticates through OIDC, runs npm stage publish, and a maintainer approves the version. This reduces both stored-secret risk and fully automated publication risk.

Why act before January 2027?

Existing tokens do not change immediately. However, npm is targeting January 2027 to remove direct publication of new package versions through bypass-2FA tokens. Projects still publishing this way should prepare their migration now.

The preferred path depends on the environment: trusted publishing with OIDC when the CI provider supports it; stage-only as a migration path for token-based automation; or both when human approval is desired before every release.

Migration checklist

  • Inventory workflows currently running npm publish.
  • Prefer trusted publishing when a compatible CI provider can use OIDC.
  • Otherwise create a stage-only token restricted to the required packages.
  • Replace npm publish with npm stage publish in automation.
  • Plan maintainer 2FA approval before release.
  • Revoke old tokens once the new flow is validated.

For the currently documented stage-only flow, npm requires npm CLI 11.15.0 or later and Node.js 22.14.0 or later.

CI should automate without concentrating every privilege

This npm change reflects a broader software supply-chain trend: reduce long-lived secrets, narrow permissions and create an explicit boundary before the most sensitive actions. A compromised pipeline remains serious, but it should not automatically become a public release.

Sources

Published September 19, 2026. Behaviors described reflect npm documentation available on this date.