GitHub Adds Staged Publishing to npm to Slow Automated Supply Chain Attacks

GitHub has made staged publishing generally available for npm, giving maintainers a new checkpoint before package updates become publicly installable. The feature, announced in the GitHub changelog, places a package version into a staging queue instead of immediately releasing it to the npm registry.

The change targets a major weakness in automated release pipelines. If an attacker compromises a CI/CD workflow, the package can still land in staging, but a maintainer must review and approve it with two-factor authentication before it goes live.

The feature arrives alongside new install-time controls in npm CLI 11.15.0. Together, the changes give developers more control over both sides of the npm supply chain: how packages get published and where dependencies can come from during installation.

How npm staged publishing works

Staged publishing replaces the direct release flow with a three-step process: stage, review, and approve. According to the npm staged publishing documentation, maintainers can submit a package to a staging area with npm stage publish, then approve it later through the CLI or npmjs.com.

The staged package is not publicly available while it waits for approval. Maintainers can inspect the staged package before release, which helps catch unexpected files, altered build output, or suspicious changes introduced through compromised automation.

The approval step requires 2FA. npm’s npm stage command reference says staging itself does not require 2FA, which makes it suitable for automated workflows, but the final approval does.

Step	Command or action	Security purpose
Stage package	npm stage publish	Uploads the package without making it installable
Review package	npm stage list, npm stage view, or npm stage download	Lets maintainers inspect the staged package before approval
Approve release	npm stage approve <stage-id>	Publishes the package after maintainer approval and 2FA
Reject release	npm stage reject <stage-id>	Stops a suspicious or unwanted package from going live

Why this matters for CI/CD security

Modern npm packages often ship through automated workflows. That makes releases faster, but it also means a stolen token, altered workflow, or compromised build job can push malicious code quickly if no human approval point exists.

Staged publishing adds proof of presence to the release process. A maintainer still needs to check the staged package and approve the final release from a trusted session, reducing the risk of a fully automated malicious publish.

GitHub recommends pairing staged publishing with trusted publishing for npm packages. That setup uses OpenID Connect to publish from CI/CD without long-lived npm tokens, while still allowing the final release to wait for maintainer approval.

New install-source controls tighten dependency rules

GitHub also added new npm install-source flags that let teams restrict non-registry dependency sources. The GitHub changelog says --allow-file, --allow-remote, and --allow-directory now join the existing --allow-git flag.

These controls matter because malicious dependencies do not always arrive from the public npm registry. Attackers can abuse Git dependencies, remote tarballs, local tarballs, or directory references if a project allows them without review.

The npm CLI documentation lists three modes for these controls: all, none, and root. The root mode lets teams allow sources declared in the project’s own package.json while blocking unexpected sources deeper in the dependency tree.

Flag	What it controls	Available modes
--allow-file	Local tarball file dependencies	all, none, root
--allow-remote	Remote URL tarball dependencies	all, none, root
--allow-directory	Local directory dependencies	all, none, root
--allow-git	Git-based dependencies	all, none, root

npm 12 will make Git installs stricter by default

The new flags currently default to all, mainly to avoid breaking existing projects. However, GitHub says the default for --allow-git will change from all to none in npm CLI v12.

That shift shows where npm security is heading. Instead of allowing every dependency source unless developers block it, npm is moving toward clearer allowlist-style behavior for risky non-registry sources.

Teams can adopt the stricter model before npm 12 by setting policies in .npmrc or package configuration. For high-security projects, blocking unexpected Git, URL, file, and directory dependencies can reduce exposure during both local installs and CI builds.

What maintainers should change now

Maintainers should start by upgrading release environments to npm CLI 11.15.0 or newer and Node 22.14.0 or higher. They should also confirm whether the package already exists on npm, since staged publishing does not support publishing the first version of a new package.

For projects that already use CI/CD releases, the safest path is to replace direct publishing with npm stage publish and require maintainers to review the staged package before approval. The npm stage command reference also includes commands to download and inspect staged tarballs.

Organizations should also review their trusted publisher settings. The trusted publishing documentation says allowed actions can include npm publish, npm stage publish, or both, which lets teams restrict automated workflows to staging only.

• Upgrade release machines and CI runners to npm CLI 11.15.0 or newer.
• Use npm stage publish for sensitive or widely used packages.
• Review staged tarballs before approving a release.
• Use trusted publishing with OIDC instead of long-lived npm tokens where possible.
• Set install-source controls to none or root where non-registry sources are not expected.
• Document exceptions for packages that still require Git, remote URL, file, or directory dependencies.

Staged publishing does not replace package review

Staged publishing reduces the risk of silent automated releases, but it does not detect malicious code by itself. A maintainer can still approve a compromised package if the review only checks version numbers or release notes.

The best workflow combines staged publishing with source restrictions, lockfile review, provenance checks, and CI/CD hardening. The npm staged publishing documentation also allows maintainers to inspect staged packages through the CLI or npmjs.com before approval.

Security teams should treat the new npm controls as practical guardrails rather than a complete defense. The npm CLI documentation warns that changing install-source settings can leave a dependency tree incomplete, so teams should test stricter settings before enforcing them across large codebases.

FAQ