Phased publishing on npm: Moving away from CI-only unattended releases

Distributing in-house shared UI components or API clients as npm packages, or having internal projects universally reference an SDK built by a contractor—this kind of setup itself is not uncommon.

The problem is that publishing relies entirely on a single token placed in CI. Push a tag, the workflow runs, and if the build passes, it gets published. No human intervenes. In terms of efficiency, it is the right design, but looked at another way, anyone who obtains that token can do the exact same thing. What's more, from the very moment a new version is published, it is distributed to npm install across the world.

Many of the supply chain attacks that occurred in quick succession in 2026 did not exploit vulnerabilities. Instead, attackers used publishing tokens stolen from CI/CD pipelines to publish tainted versions through legitimate procedures. The build passes, the signature is genuine, and the publisher is an authorized account. Detection is difficult because nothing appears out of the ordinary.

Returning only the final step to human hands

In response, npm introduced a mechanism that inserts human approval immediately prior to publication: staged publishing, which became available for all packages on May 22, 2026.

Here is how it works. When you run npm stage publish instead of npm publish, the package is not placed on the registry; instead, it enters a staging queue. At this stage, no one can install it. Only after a maintainer authenticates with two-factor authentication and approves it is it finally published.

Operations are handled entirely with the following subcommands:

npm stage publish              # ステージングキューに積む（2FA不要・CIから実行できる）
npm stage list                 # 承認待ちの一覧を見る
npm stage view <stage-id>      # 中身（tarball）を確認する
npm stage approve <stage-id>   # 2FA を通して公開する
npm stage reject <stage-id>    # 破棄する

npm stage publish does not prompt for 2FA, regardless of the token type. This is the key architectural insight. CI continues to handle building and staging packages automatically as before, leaving only the decision to publish to the world in human hands. Without weakening CI security, the maximum damage from a compromised token is capped at merely "adding a package to the publishing queue."

The recommended configuration: "CI only queues"

The combination recommended by GitHub pairs trusted publishing via OIDC with staged publishing. By setting workflow permissions to stage-only, npm stage publish succeeds while npm publish is rejected.

Only once this setting is in place are the loopholes closed. If you introduce staged publishing while the conventional npm publish remains usable, attackers will simply use that instead. An approval gate only truly becomes a gate once bypass routes are shut down.

Around the same time, controls for the installation side (options in the --allow-* family) were also added. Because updates have been made to both the publishing and consuming sides, the features you should pay attention to depend on which side your organization is on. For organizations that do not distribute packages, the latter provides a more direct impact.

Things to verify before adoption

The requirements are npm CLI 11.15.0 or later and Node.js 22.14.0 or later. If your CI runner is pinned to an older version of Node, you will run into issues here. Please verify the version specifications in your release workflows first.

There are also several constraints.

New packages cannot use staged publishing. It applies only to packages that already exist on the registry. The very first release must still be published the conventional way.

Tags assigned during staging cannot be modified later. If you want to change what was queued under latest to next, you must first discard it with npm stage reject and stage it again. If your release process is prone to mistagging, organizing this beforehand will help minimize confusion.

Compatibility issues with release tooling can arise. If you use automated release tools like changesets, implementations that invoke npm publish directly will bypass the staged publishing pathway. Check their support status before deciding when to migrate.

Preventing it from becoming a mere formality

Approval gates often start becoming mere formalities the month after they are introduced. Decide on preventive measures at the outset.

Do not rely on a single approver. If releases depend on the presence of one person, emergency patches cannot be shipped when they are away. If an exception like "the approver is away, so we published directly this time" is allowed even once, that bypass route will become habitual.

Define what to look for during approval. Even with a mechanism to inspect contents via npm stage view, without clear criteria to evaluate, it turns into a thoughtless clicking exercise. The number of changed files, unexpected files mixed in, added dependencies, the presence of postinstall scripts—even establishing basic criteria like these makes a substantial difference. What scripts running at installation time can do is covered under The premise that npm install runs arbitrary code.

Build the waiting time for approval into release planning. If you build schedules assuming releases can be shipped instantly, the moment approval becomes a bottleneck, pressure will mount to remove the gate.

What changes for consumers

If your organization does not distribute packages, this feature does not concern you directly. However, whether your critical upstream dependencies have adopted staged publishing affects your risk assessment. Packages that use it are significantly less vulnerable to the release of tainted versions caused by token leaks.

Still, this is a countermeasure on the publishing side. Defenses on the consuming side are required separately, and practices that introduce a time delay before adopting new dependencies remain effective. This concept was outlined in Dependabot cooldowns are now default. It is a mechanism designed to avoid walking right into the window of a few hours between when a tainted version is published and when it gets revoked.

What to ask your contractors

If you have external vendors build packages for internal use or outsource maintenance to them, confirming the following points will help you understand the situation:

1. Is publishing for that package automated via CI? If an individual is publishing manually from their local environment, that introduces an entirely different set of risks
2. When was the token used for publishing issued? The risks of leaving long-lived tokens abandoned and unrotated were discussed in Is your contractor's build environment still running on long-lived tokens?
3. Are there plans to adopt staged publishing or an equivalent approval gate? Deciding not to adopt it is acceptable, but whether the reason is "we didn't know about it" or "it is operationally difficult" changes how you should interpret the response
4. How many people are authorized to approve? If there is only one, also check the procedure for when that person is unavailable

These questions are not meant to express doubt toward contractors, but are checks to ensure both parties understand potential attack vectors. When a supply chain incident actually occurs, the most time-consuming part is figuring out where the compromise originated. The broader scope of these attacks is summarized in Supply chain attacks in 2026.

What to do next

Pick one package your company publishes to the npm registry and open its release workflow. What you should check is whether the step executing npm publish completely lacks any human approval. If there is none, a tainted version will be published the moment that token is leaked.

If you do not publish any packages, count how many of your dependencies were built internally or by contractors. That represents the practical boundary of your organization's supply chain.

GleamHub provides consultations on development, AI, and automation, including integrating approval gates into release workflows and designing permission architectures for build environments, including those of contractors. Because the pragmatic compromise varies depending on your development setup and release frequency, please consult with us individually via Contact Us.

Sources

• Staged publishing and new install-time controls for npm — GitHub Changelog（2026-05-22）
• Staged publishing for npm packages — npm Docs
• npm-stage — npm Docs
• npm Staged Publishing Available, Adding a Human Approval Step Before Packages Go Live — InfoQ
• npm Adds 2FA-Gated Publishing and Package Install Controls Against Supply Chain Attacks — The Hacker News