Skip to content
Merged
28 changes: 14 additions & 14 deletions content/cli/v11/commands/npm-stage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -61,14 +61,14 @@ Before using `npm stage` commands, ensure the following requirements are met:

### 2FA Requirements by Subcommand

| Command | Requires 2FA | Notes |
| --- | --- | --- |
| `npm stage publish` | No | Designed for automated workflows; defers 2FA to approval |
| `npm stage list` | No | View staged packages |
| `npm stage view` | No | View staged package details |
| `npm stage approve` | Yes | Prompts for 2FA to publish the staged package |
| `npm stage reject` | Yes | Prompts for 2FA to permanently remove the staged package |
| `npm stage download` | No | Downloads the tarball for local inspection |
| Command | Requires 2FA | Notes |
| -------------------- | ------------ | -------------------------------------------------------- |
| `npm stage publish` | No | Designed for automated workflows; defers 2FA to approval |
| `npm stage list` | No | View staged packages |
| `npm stage view` | No | View staged package details |
| `npm stage approve` | Yes | Prompts for 2FA to publish the staged package |
| `npm stage reject` | Yes | Prompts for 2FA to permanently remove the staged package |
| `npm stage download` | No | Downloads the tarball for local inspection |

### Tag Behavior

Expand All @@ -80,12 +80,12 @@ The tag is an immutable property of the staged package. Once a package is staged

The key difference with staged publishing is that `npm stage publish` never requires a 2FA prompt, regardless of token type. This is what makes it suitable for automated workflows. The goal of `npm stage publish` is deferring proof-of-presence to a later point in time.

| Token Type | `npm stage publish` | `npm publish` |
| --- | --- | --- |
| GAT with bypass | Can stage | Can publish (if allowed by package publishing access) |
| GAT without bypass | Can stage | 2FA prompt (if allowed by package publishing access) |
| Session token | Can stage | 2FA prompt |
| Trust token (OIDC) | Can stage (if allowed) | Can publish (if allowed) |
| Token Type | `npm stage publish` | `npm publish` |
| ------------------ | ---------------------- | ----------------------------------------------------- |
| GAT with bypass | Can stage | Can publish (if allowed by package publishing access) |
| GAT without bypass | Can stage | 2FA prompt (if allowed by package publishing access) |
| Session token | Can stage | 2FA prompt |
| Trust token (OIDC) | Can stage (if allowed) | Can publish (if allowed) |

### Trust Relationship Permissions

Expand Down
28 changes: 14 additions & 14 deletions content/cli/v12/commands/npm-stage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,14 +77,14 @@ Before using `npm stage` commands, ensure the following requirements are met:

### 2FA Requirements by Subcommand

| Command | Requires 2FA | Notes |
| --- | --- | --- |
| `npm stage publish` | No | Designed for automated workflows; defers 2FA to approval |
| `npm stage list` | No | View staged packages |
| `npm stage view` | No | View staged package details |
| `npm stage approve` | Yes | Prompts for 2FA to publish the staged package |
| `npm stage reject` | Yes | Prompts for 2FA to permanently remove the staged package |
| `npm stage download` | No | Downloads the tarball for local inspection |
| Command | Requires 2FA | Notes |
| -------------------- | ------------ | -------------------------------------------------------- |
| `npm stage publish` | No | Designed for automated workflows; defers 2FA to approval |
| `npm stage list` | No | View staged packages |
| `npm stage view` | No | View staged package details |
| `npm stage approve` | Yes | Prompts for 2FA to publish the staged package |
| `npm stage reject` | Yes | Prompts for 2FA to permanently remove the staged package |
| `npm stage download` | No | Downloads the tarball for local inspection |

### Tag Behavior

Expand All @@ -96,12 +96,12 @@ The tag is an immutable property of the staged package. Once a package is staged

The key difference with staged publishing is that `npm stage publish` never requires a 2FA prompt, regardless of token type. This is what makes it suitable for automated workflows. The goal of `npm stage publish` is deferring proof-of-presence to a later point in time.

| Token Type | `npm stage publish` | `npm publish` |
| --- | --- | --- |
| GAT with bypass | Can stage | Can publish (if allowed by package publishing access) |
| GAT without bypass | Can stage | 2FA prompt (if allowed by package publishing access) |
| Session token | Can stage | 2FA prompt |
| Trust token (OIDC) | Can stage (if allowed) | Can publish (if allowed) |
| Token Type | `npm stage publish` | `npm publish` |
| ------------------ | ---------------------- | ----------------------------------------------------- |
| GAT with bypass | Can stage | Can publish (if allowed by package publishing access) |
| GAT without bypass | Can stage | 2FA prompt (if allowed by package publishing access) |
| Session token | Can stage | 2FA prompt |
| Trust token (OIDC) | Can stage (if allowed) | Can publish (if allowed) |

### Trust Relationship Permissions

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,8 @@ For more information on the `publish` command, see the [CLI documentation][cli-p

Instead of publishing directly, you can stage your package and approve it later. Staging the package does not require 2FA, which allows CI workflows to submit a package to the staging area. Before the package is published to the registry, a maintainer must review and approve it with 2FA.

If the package does not yet exist, staging it publishes a placeholder version of the package that is publicly available. The staged version and its contents are not available until the staged package is approved.

A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.

1. On the command line, navigate to the root directory of your package.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,8 @@ For more information on the `publish` command, see the [CLI documentation][cli-p

Instead of publishing directly, you can stage your package and approve it later. Staging the package does not require 2FA, which allows CI workflows to submit a package to the staging area. Before the package becomes publicly available, a maintainer must review and approve it with 2FA.

If the package does not yet exist, staging it publishes a placeholder version of the package that is publicly available. The staged version and its contents are not publicly available until the staged package is approved.

A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.

1. On the command line, navigate to the root directory of your package.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,8 @@ For more information on the `publish` command, see the [CLI documentation][cli-p

Instead of publishing directly, you can stage your package and approve it later. Staging the package does not require 2FA, which allows CI workflows to submit a package to the staging area. Before the package becomes publicly available, a maintainer must review and approve it with 2FA.

If the package does not yet exist, staging it publishes a placeholder version of the package that is publicly available. The staged version and its contents are not publicly available until the staged package is approved.

A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.

1. On the command line, navigate to the root directory of your package.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ Staged publishing adds an approval step before packages go live on the npm regis

Staged publishing is useful when you want an extra review step before a package version becomes available on the registry.

You can use staged publishing for both new and existing packages. When you stage a package that does not yet exist, npm publishes a placeholder version of the package with the version `0.0.0-stage`. This placeholder version is publicly available, but the staged version and its contents are not publicly available until a maintainer approves the staged package. After approval, the staged version is published to the package page.

<Note>

**Note:** Staged publishing requires [npm CLI](https://docs.npmjs.com/cli/v11) version 11.15.0 or later and Node version 22.14.0 or higher.
Expand All @@ -25,7 +27,6 @@ Staged publishing has three steps:
Before using staged publishing, ensure the following:

- You have **publish access** to the package
- The package **already exists** on the npm registry — you cannot stage a brand-new package
- **2FA is enabled** on your npm account

## Stage a package
Expand Down
122 changes: 68 additions & 54 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading