npm Stage-Only Tokens: Evidence to Keep When Separating Deployment Automation and Final Approval
Separating the permission for CI to build packages from the permission to publish them to users brings greater clarity to the final responsibility of a release. However, simply adding an approval button does not make supply chain risks disappear. You must first define what the approver actually reviews.
On September 18, GitHub announced that granular access tokens for npm can now be configured with stage-only write permissions. In this workflow, automation submits a version into a pending-review state, and a maintainer approves publication using 2FA. Below is an explanation distinguishing the official changes from editorial recommendations for putting them into operation.
Blocking Direct Publishing Is Not the Same as Removing Write Permissions
According to the official guidance, you can run npm stage publish with these tokens, but direct publishing via npm publish is rejected. This restriction applies even if a 2FA bypass for automation is configured. It does not automatically alter the behavior of existing tokens and is an opt-in feature.
A critical point to note is that other package write permissions—such as moving dist-tags and deprecating versions—remain. The "stage-only" label should not be interpreted as meaning a read-only or harmless token. You still need to govern allowed package scopes, secret storage locations, authorized actors, and revocation procedures.
Define the Release Bundle That Approvers Compare
The following points are operational suggestions for small teams, not mandatory npm configurations. In each approval request, include the source commit, target package and version, test results, list of files packaged, and a change summary. If approvers must piece together evidence from scattered CI logs, reviews can easily devolve into perfunctory rubber-stamping.
In particular, reviewing source code is distinct from reviewing deployment artifacts. Files not present in the repository could be included during the build process, or essential files might be omitted. Teams can establish a principle of assembling review materials based on the actual submitted artifacts and treating any artifact modified after review as requiring an entirely new review.
There Is Still a Pending State After a Green CI
If existing automation reported command success as a completed release, you should start by updating how statuses are represented. Separate the flow into submission complete, awaiting approval, and published, recording the verification basis for each. In notifications, stating the current stage and the assigned reviewer is far more useful to operators than simply saying "Success."
As a hypothetical example, if a nightly CI run submits a new version but the maintainer will not review it until the following day, user-facing release announcements must not be dispatched at submission time. Sequence documentation and announcements to trigger only after the team's defined publication confirmation. You should also agree in advance on who reviews queued items when they accumulate and when to clean up superseded submissions.
Validate Migration with a Single Small Package
The prerequisites in the current official guidance include an existing npm package, publish rights to the package, account 2FA, npm CLI 11.15.0 or higher, and Node.js 22.14.0 or higher. Before an actual migration, verify the latest documentation and check the runner versions in use.
We recommend starting with a single low-impact package, restricting its token scope, and practicing the full flow: staging submission, maintainer review, and verifying publication results. If failures immediately fall back to legacy tokens with broader permissions, the separated boundaries become meaningless. Approval delays must also be treated as a normal operational state.
Questions to Compare with Trusted Publishing
npm also offers trusted publishing using OIDC. First evaluate whether it fits your supported CI environment and your team's approval model; there is no reason to generalize stage-only tokens as the definitive solution for every team. For automations that must continue using tokens, this can be viewed as providing an option for phased migration.
The official announcement points to January 2027 as the target date for removing direct publishing via bypass-2FA tokens. Rather than speculating on every finalized implementation detail, it is practical now to compile a list of targeted workflows and assign migration owners. Future schedule updates should be verified through subsequent official announcements.
When Deciding on Adoption
This article does not claim broad community consensus or measurable incident reduction rates. It suggests reviewable operational procedures based on the official behavior of the new feature. Being able to articulate what automation handles versus what humans verify is the starting point for deciding whether to adopt it.
What you can do today is locate where release tokens are currently used, write down the criteria that define completed publication, and specify the evidence required for a single approval. Only when permission scoping and review quality are addressed together does the staging phase truly deliver value.