A stage-only npm granular access token lets CI upload a package version for review without directly publishing that version to the public registry. The release job runs npm stage publish; a maintainer then inspects the pending stage and approves or rejects it. This adds a human gate, but it does not remove every write permission from the token. For supported CI providers, npm recommends trusted publishing with OIDC instead of keeping a long-lived publishing token.
What a stage-only npm token does
In npm’s granular-token permissions, Read and write (stage only) allows the token to stage a new package version but not to publish that version directly. If the job tries npm publish, npm rejects the operation with E_STAGE_REQUIRED. The intended release command is npm stage publish, which creates a pending stage for a maintainer to review.
As an Amazon Associate I earn from qualifying purchases.
npm describes stage-only tokens as “a safer on-ramp” for CI/CD automation. The distinction matters: staging changes the release path, not the identity or overall trustworthiness of the automation that holds the credential. npm’s access-token documentation explicitly warns that stage-only is not a general-purpose security boundary.
How the staged release process works
Staged publishing separates uploading a candidate from making it available as a published package version. npm says the mechanism requires proof of presence for publishes; the documented token workflow places a maintainer’s approval between the CI upload and publication. Approval requires 2FA.
#1 Best Overall
- CI uploads the candidate: the release job authenticates with the stage-only credential and runs
npm stage publish, notnpm publish. - A maintainer reviews the stage: list pending stages with
npm stage list, inspect one withnpm stage view <stage-id>, or download it for review. - The maintainer decides: approve with
npm stage approve <stage-id> --otp <code>, supplying the required one-time password, or reject withnpm stage reject <stage-id>.
See npm’s staged publishing CLI reference for command details and its 2FA policy documentation for account and publishing requirements.
What stage-only does not prevent
The boundary is specifically about directly publishing new versions. npm says a stage-only token retains other write capabilities, including deprecating package versions and moving dist-tags. A compromised token could therefore still affect consumers through those actions even though npm publish is blocked.
Restrict the token to only the packages or scopes the job needs, set an expiration, and consider allowed IP ranges when the runner has stable egress addresses. Store it in the CI secret manager and expose it only to the release job, not install-and-test jobs. Granular tokens remain constrained by the account’s permissions. npm documents limits of up to 1,000 granular tokens per account and access to up to 50 organizations and 50 packages/scopes in combination; these are service limits, not security guarantees. The permission controls are described in Creating and viewing access tokens and the npm-token CLI reference.
Stage-only tokens versus trusted publishing
These are distinct mechanisms. A stage-only granular token is a stored credential with a permission setting that routes releases through staging. Trusted publishing uses a CI provider’s OIDC identity to obtain short-lived, workflow-specific npm credentials, avoiding a long-lived publishing token. npm recommends trusted publishing where it is supported.
| Choice | Credential exposure | Release gate | Provider and prerequisites |
|---|---|---|---|
| Stage-only granular token | Long-lived until it expires or is revoked; restrict packages/scopes, expiration, and optionally IP ranges. | Stages a version; maintainer approval is required before it is published. Direct npm publish is rejected. |
Works as a token-based workflow; keep it in CI secrets and expose it only to the release job. |
| OIDC trusted publishing | Short-lived credentials issued for the trusted workflow; avoids maintaining a long-lived npm publish token. | Trust can be configured to allow stage publishing without allowing direct publishing. A trust configuration must allow at least one of --allow-publish or --allow-stage-publish. |
npm documents GitHub Actions on GitHub-hosted runners and GitLab CI/CD on GitLab.com shared runners. Trusted publishing requires npm CLI 11.5.1 or later and Node 22.14.0 or later; npm’s trust commands require CLI 11.15.0 or later. |
Trusted publishing currently supports cloud-hosted runners; npm says self-hosted runner support is intended for a future release. The npm account needs account-level 2FA and write access to an existing package to configure trust. Bypass-2FA granular tokens cannot be used as the authentication method to configure a trust relationship. Consult the current trusted publishing setup and npm trust CLI reference before rollout: provider support, version thresholds, and setup details can change.
For an additional release gate, configure the OIDC relationship to allow stage publishing but not direct publishing. npm does not validate every trusted-publisher configuration when saved, so verify the exact setup in a test workflow before depending on it. For GitHub Actions, the repository URL must match the value in package.json, and the repository and workflow settings must identify the intended publisher.
Keep dependency installation separate from publishing
Most CI jobs that only install dependencies and run tests do not need publishing rights. npm recommends a read-only granular token as the safer credential for CI workflows that install packages. If dependencies are private, that token may still be needed: OIDC trusted publishing authenticates publishing and is not intended for npm install. Keep the read-only credential separate from the release credential and limit which jobs can access it. npm’s CI/CD guidance for private packages also recommends disabling package-manager caching in release builds in its GitHub Actions example.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choosing and rolling out a release path
- Prefer trusted publishing when the project uses a supported provider and can meet npm’s runner, CLI, Node, account, and repository-configuration requirements.
- Use stage-only tokens when a token-based release path is needed and the team can review and approve every staged release. Treat the token’s deprecation and dist-tag permissions as real residual risk.
- Keep install credentials read-only and separate from the job that publishes or stages releases.
- Test before removing the old path: verify the workflow’s exact identity, permissions, package configuration, and commands. For trusted publishing, test the relationship because npm does not validate all configuration when it is saved.
When migrating, establish and verify trusted publishing first, then restrict traditional token publishing and revoke unused automation tokens. If retaining a stage-only token, change the release command from npm publish to npm stage publish and make the human review step explicit.
Policy timing for Bypass-2FA tokens
npm’s access-token documentation states that direct publishing by Bypass-2FA granular tokens is scheduled for removal in January 2027. It also says that, starting August 2026, those tokens cannot perform account-identity or account-governance actions, which still require an interactive 2FA challenge. These dates reflect npm’s documented policy timeline; check the current access-token guidance as the dates approach.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
