npm Staged Publish: Secure CI/CD Release Workflow

Introduction

Automated release pipelines do not grant CI systems unrestricted permission to publish packages directly to public registries. GitHub and npm have introduced a new type of scoped access token to restructure package delivery workflows. The updated mechanism allows CI infrastructure to build and stage package artifacts, while human maintainers explicitly approve public release afterward. For package maintainers, the core benefit of this staged token model is straightforward. Even if a token gets leaked, attackers cannot run npm publish to push new live versions into production. This token still carries write permissions, however, and should never be treated as fully harmless credentials. This article breaks down the technical background, workflow design, implementation examples, risk boundaries and migration recommendations for npm staged publishing.

What Changed on npm and GitHub

GitHub announced the new permission scope on September 18: npm granular access tokens now support a Read and write (stage only) permission mode. CI workflows running npm CLI version 11.15.0 or newer can execute the npm stage publish command. This action sends built packages into a pending staging queue, instead of publishing them immediately. Maintainers with package publishing rights then complete final approval with two-factor authentication (2FA). The minimum Node.js runtime requirement is version 22.14.0, and existing npm packages require no modification to adopt this feature.

The official announcement and npm staged release documentation serve as primary reference sources. A critical timeline is also specified: npm plans to remove legacy token capabilities that bypass 2FA for direct package publishing by January 2027. At the time of writing, staged publishing is an opt-in migration path, and existing tokens will not be automatically hardened or revoked. Teams retain full control over the pace of adoption.

Core Judgement: Segregating Permissions by Risk

Traditional npm automated release pipelines bundle build, upload and public publication under a single token credential. Once a workflow relies on third-party GitHub Actions, or the token is exposed through logs, any attacker who captures this token gains permission to publish new package versions visible to all registry users.

Stage-only tokens split this single high-risk operation into two separate steps: submitting a candidate package and approving that candidate for public listing. This design mirrors dual-control separation, comparable to the maker-checker approval logic widely used in banking systems.

This analogy carries clear boundaries. npm stage-only tokens are not read-only credentials. Official documentation confirms they retain permissions to modify distribution tags, deprecate existing package versions and run related administrative actions. These operations can redirect the latest tag to incorrect releases or mark healthy package versions as deprecated. The security improvement introduced by staged publishing is limited. It blocks the creation of new public package releases, rather than eliminating every possible supply-chain attack vector.

The revised end-to-end workflow can be described sequentially:

1. Code merge triggers CI build and test tasks

2. CI generates package artifacts and provenance attestations

3. CI runs npm stage publish to submit candidates to staging

4. Human maintainers conduct review

   • If rejected: rebuild fixes and re-submit

   • If approved: complete 2FA verification

5. The package becomes publicly available after approval

6. Maintainers validate package versions and distribution tags

Migratable Workflow Implementation

Teams first create a stage-only token targeting the desired package scope inside npm backend, and save this token as a repository secret named NPM_STAGE_TOKEN. The example workflow below demonstrates staged submission, without automatic approval.

name: stage-package
on:
  workflow_dispatch:
    inputs:
      version:
        description: "Version to stage for release"
        required: true
jobs:
  stage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: "22.14.0"
          registry-url: "https://registry.npmjs.org"
      - run: npm ci
      - run: npm test
      - run: npm version "${{ inputs.version }}" --no-git-tag-version
      - run: npm pack --dry-run
      - run: npm stage publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_STAGE_TOKEN }}

Three critical points define this workflow:

1. workflow_dispatch: Triggers the pipeline manually instead of generating candidate packages after every single code merge. This prevents excessive staging submissions.

2. npm pack --dry-run: Validates file inclusion before submission, verifying exactly which assets will be bundled inside the final package.

3. Environment variable injection: The token is delivered through environment variables only. It cannot be written into local .npmrc files.

Hard requirements for running this workflow include Node.js 22.14.0 or higher, npm CLI 11.15.0+, maintainer write permissions on the target package, and 2FA enabled for the maintainer account.

This YAML sample is not validated on a live runtime environment. It lacks access to real npm packages, accounts and valid stage-only tokens. It passes structural and field inspection only and should not be interpreted as proof of successful package staging.

Impacts for Development Teams

Small teams often view manual approval as a bottleneck slowing releases. The optimal migration strategy is not a full rollback to manual local packaging. Instead, teams delegate repeatable build and validation tasks to machines while reserving high-risk public release actions for human reviewers.

When conducting reviews, maintainers should examine version diffs, file manifests generated by npm pack, test outputs, build provenance records and change logs. Reviews should never reduce to a simple one-click approval without inspection.

For repositories with multiple packages, separate tokens should be provisioned per-package or per-group. This prevents CI pipelines for one frontend component from gaining permission to modify packages across the entire organization. For high-frequency, unattended release workflows where feasible, teams can also evaluate npm trusted publishing, which uses short-lived identity tokens instead of long-lived static credentials. Stage-only tokens are most suitable for teams unable to migrate to trusted publishing immediately, but still need to reduce credential risk ahead of npm’s 2027 policy enforcement.

Migration sequencing matters significantly. Teams should avoid replacing all production tokens on day one. Start by selecting a low-risk package to test candidate staging. Validate normal approval paths, rejection flows, rollbacks, and version re-testing after rejection. Once validated, integrate audit logs with existing security tooling, and define notification windows for reviewers.

The goal of this process is not to increase meeting overhead. It ensures primary maintainers cannot be pressured into restoring high-privilege tokens during urgent hotfixes when core maintainers are offline.

Approval pages must retain stable traceability links back to source commits. Candidate packages need immutable correlation identifiers linking package version numbers, Git commit summaries, workflow run IDs, dependency lock files and package manifests. If reviewers only see a simple version string such as 1.2.3, attackers may exploit version naming races and concurrent workflow jobs to trick approvers. Embedding build artifact hashes into release notes ties every approval action to a specific verified build artifact.

Risk Boundaries and Action Checklist

Even after adopting staged publishing, several critical risk points remain unresolved:

1. Stage-only tokens retain the ability to modify distribution tags and deprecate package versions. Like all write tokens, they must be rotated regularly, scoped narrowly, and monitored for abnormal operations.

2. Human review workflows degrade into rubber-stamp approval if reviewers only check version numbers without inspecting artifacts.

3. 2FA protects maintainer accounts, but it cannot substitute for build isolation, credential locking, and cryptographic provenance validation.

Four immediate tasks teams can complete within the same week:

1. Inventory all existing NPM_TOKEN credentials currently used within CI pipelines.

2. Mark tokens that carry direct publishing privileges for replacement or restriction.

3. Create stage-only tokens for high-risk core packages.

4. Validate end-to-end workflows covering staging submission, rejection, approval and rollback.

The most practical improvement for software supply chain security is not adding more scanning rules. It removes irreversible capabilities from credentials that could be stolen. Once migration finishes, teams should revoke old publish tokens actively and scan caches, logs and historical configuration files to eliminate residual credential exposure.

When managing multiple registries and CI credential routing, teams may use an API gateway to centralize authentication rules across different package and service endpoints. 4sapi, an API gateway, helps standardize credential rotation, access logging and request routing for various backend services, complementing registry-side permission controls like npm staged publishing.

Conclusion

npm staged publishing addresses one of the most dangerous failure modes in automated software release pipelines: token leakage leading to immediate public package compromise. By separating artifact staging from final public approval, it introduces human gatekeeping before irreversible publication occurs.

It is important to avoid overstating this feature’s protective scope. It does not block tag modifications, deprecation actions, or insider threats. It will not replace supply-chain scanning, provenance validation, or least-privilege access design. It serves as one strong control layer within a broader security strategy.

Teams planning long-term security roadmaps should start small, test workflows on low-impact packages first, and build audit trails for every staged candidate. The deadline of January 2027 for legacy token deprecation gives engineering teams time to plan, but delaying migration creates avoidable exposure. Every pipeline needs evaluation to identify which actions should move from fully automated execution to explicit human approval.

International access: https://4sapi.com

Domestic access: https://4sapi.cn