A narrower permission for automated publishing

GitHub says npm users can now choose Read and write (stage only) when creating a granular access token. The permission is designed for automated workflows that need to submit package versions but should not be able to publish new versions directly to the npm registry.

With a stage-only token, a workflow uses npm stage publish rather than npm publish. The submitted version is then held for review, allowing a package maintainer to decide whether to approve its release. Approval requires the maintainer to authenticate with two-factor authentication (2FA).

Direct publication is blocked

The new token type specifically separates staging from direct publication. npm rejects attempts to run npm publish with a stage-only token, including cases where the token has been configured to bypass 2FA for automation.

That restriction is intended to prevent an automated credential from completing the entire release process on its own. Instead, automation can prepare and submit a version while a maintainer remains responsible for the final approval step.

Other package permissions remain available

Stage-only tokens are not read-only credentials. GitHub notes that they retain other package write permissions, including the ability to move distribution tags and deprecate versions.

Because of those capabilities, the tokens should be protected with the same care as any other write token. The stage-only setting limits direct publishing, but it does not eliminate the broader impact of a compromised credential with package write access.

An opt-in path for existing automation

The release does not alter existing tokens or their current direct-publish capabilities. Teams must opt in by creating a new granular access token with Read and write (stage only) permissions for the packages their workflows require.

GitHub’s migration steps are straightforward: replace the workflow’s existing publishing token, change the command from npm publish to npm stage publish, and have a maintainer review and approve each staged version with 2FA. Staged publishing also works with existing npm packages.

Preparing for the planned token transition

The feature provides a migration option for teams that rely on token-based automation and are not yet able to move to trusted publishing. GitHub says npm is targeting January 2027 to remove direct publishing through tokens that bypass 2FA.

To use staged publishing, a team needs publish access to the package, 2FA enabled on its npm account, npm CLI 11.15.0 or later, and Node.js 22.14.0 or later. These requirements apply alongside the workflow changes needed to submit and approve staged releases.

Sources

• GitHub ChangelogStage-only npm tokens for safer automation