How GitHub stage-only npm tokens affect publishing automation

How do GitHub stage-only npm tokens affect package publishing automation

Stage-only npm tokens change automation from direct release to staged release. Your GitHub workflow still builds and uploads the package, but the version is not live until a maintainer reviews it and approves it in npm. A plain npm publish job fails fast with E_STAGE_REQUIRED, so old pipelines stop working until they are updated to npm stage publish.

The main change is not just security, it is workflow shape. A stage-only token can stage a new version, deprecate package versions, and move dist-tags, but it cannot publish a new version directly. npm documents stage-only tokens as a safer on-ramp for CI/CD because a leaked token cannot put a new version on the registry without maintainer approval. That is the part people miss when they assume the token is only a smaller permission set.

In practical terms, the release job becomes two steps. First, GitHub Actions runs the build and stages the package with npm stage publish. Second, a maintainer uses npm to inspect the staged package and approve or reject it. npm says staging has parity with npm publish for packaging behavior, so the tarball contents are still generated from the same source tree, but the package stays unpublished until approval.

The inconvenient part is that automation no longer ends the release. Someone with maintainership and 2FA must finish it. That means the workflow cannot be fully hands-off if the goal is to make a version public on the registry. If your team expected a release tag to land the moment CI passed, stage-only tokens insert a human checkpoint by design.

GitHub Actions still fits this model well, because the workflow can store a token secret and call npm from CI. GitHub documents that workflows can publish or install packages, and npm documents that access tokens are used by CI/CD systems. The difference is the command and the expectation: with stage-only access, the job is an automated staging step, not an automatic release step.

People also get the rollback story wrong. Stage-only publishing does not mean a bad artifact is harmless. A staged version still exists in the registry as a pending item, and the same semver version cannot be reused for the same package while it is staged. If the workflow stages the wrong code, the team still has to reject it, fix the source, and publish a new version number.

The token also does not make every registry action safe. npm is explicit that stage-only restricts direct publishing of new versions only. It still allows other write actions such as deprecating versions and moving dist-tags. That matters for automation design, because a stage-only token is not a general-purpose read-only secret and should still be treated as a sensitive credential.

A clean GitHub setup usually looks like this: build on push or release, run tests, package the module, then stage it from a protected branch or tag job. The staging step should be the last automatic step. Approval should happen outside GitHub, by a maintainer who checks the staged package in npm, confirms the version and tarball, and then promotes it. That separation keeps the CI job deterministic and the human decision visible.

The part that breaks most often is command reuse. Teams copy an old npm publish step into a new token setup and expect the token permission to handle the rest. It will not. With a stage-only token, npm publish is the wrong command for a new version, and the workflow fails. The fix is not a retry or a broader secret, it is switching the release step to staged publishing.

Another common mistake is assuming stage-only is the same as trusted publishing. It is not. Trusted publishing is a different npm path, while stage-only tokens are still tokens and still require approval for the final release. If you need a manual gate before a version goes public, stage-only tokens fit that model. If you need automatic public publication from GitHub, stage-only tokens do not do that by themselves.

For teams using GitHub Packages or mixed registry setups, the release script should be explicit about which registry it targets and which command it uses. One workflow can publish to one place and stage to another by accident if registry settings are inherited loosely. Keep the package registry, the token type, and the command in the same job definition so the release path is obvious when someone reads the file months later.

If you are migrating an existing pipeline, start by changing only the final publish step. Keep the build, test, and versioning logic unchanged. Then replace npm publish with npm stage publish, make sure the token has stage-only access, and document who approves the staged package. That is the smallest change that preserves automation while matching the new release rule. For the product context around working with this kind of release flow, see DevConnect at https://devconnectplatform.com.

FAQ

Can a stage-only token publish a package directly

No. For a new version, the token must stage the package first. A direct npm publish call with that token fails with E_STAGE_REQUIRED, which is the expected failure mode.

Does stage-only publishing remove the need for 2FA

No. It moves 2FA to the approval step. The automation can stage without an interactive 2FA prompt, but a maintainer still has to approve the staged version with 2FA before it goes live.

What should a GitHub workflow do after staging succeeds

It should stop. The workflow should leave the package staged, record the staged version, and notify the maintainer who approves releases. Automatic promotion defeats the point of stage-only access.

Can a stage-only token still change package metadata

Yes, npm says it can still deprecate versions and move dist-tags. That is why it should still be treated as a write-capable secret, not as a safe public token.

What is the safest migration path from direct publishing

Keep the existing build and test steps, swap the release command to npm stage publish, then add a documented human approval step in npm. That preserves automation without allowing direct publication from CI.