Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 203cdd5

Browse files
karenjlikarenjli
authored
Add documentation for staged publishing (#1961)
## Summary Updates npm publishing documentation for staged publishing and trusted publishing. - clarifies direct publishing vs. staged publishing requirements in package publishing docs - simplifies the staged publishing guide to focus on the user workflow - adds npmjs.com screenshots for reviewing and approving staged packages - updates trusted publisher screenshots and related documentation copy
1 parent 4dce668 commit 203cdd5

11 files changed

Lines changed: 278 additions & 22 deletions

‎content/nav.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,8 @@
158158
url: /generating-provenance-statements
159159
- title: Trusted publishing with OIDC
160160
url: /trusted-publishers
161+
- title: Staged publishing
162+
url: /staged-publishing
161163
- title: About ECDSA registry signatures
162164
url: /about-registry-signatures
163165
- title: Verifying ECDSA registry signatures

‎content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-private-packages.mdx‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -81,16 +81,19 @@ npm install my-package
8181

8282
By default, scoped packages are published with private visibility.
8383

84-
<Note variant="warning">
84+
There are two ways to publish your package to the npm registry:
8585

86-
**Important:** Publishing to npm requires either:
86+
1. [Direct publishing](#direct-publishing)
87+
2. [Staged publishing](#staged-publishing)
8788

88-
- Two-factor authentication (2FA) enabled on your account, OR
89-
- A granular access token with bypass 2FA enabled
89+
### Direct publishing
9090

91-
For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
91+
To publish directly with `npm publish`, you need either:
9292

93-
</Note>
93+
- Two-factor authentication (2FA) enabled on your account, or
94+
- A granular access token (GAT) with bypass 2FA enabled
95+
96+
For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
9497

9598
1. On the command line, navigate to the root directory of your package.
9699

@@ -110,6 +113,42 @@ For more information, see the npm documentation on [requiring 2FA for package pu
110113

111114
For more information on the `publish` command, see the [CLI documentation][cli-publish].
112115

116+
### Staged publishing
117+
118+
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.
119+
120+
A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
121+
122+
1. On the command line, navigate to the root directory of your package.
123+
124+
```
125+
cd /path/to/package
126+
```
127+
128+
2. To stage your package, run:
129+
130+
```
131+
npm stage publish
132+
```
133+
134+
This submits your package to a staging area.
135+
136+
3. To check that your package has been staged, use either of the following methods:
137+
- In the CLI, run `npm stage list <package-name>` to find the staged package and its stage ID.
138+
- On [npmjs.com](https://www.npmjs.com), open the **Staged Packages** tab to review staged packages.
139+
140+
4. To approve and publish the staged package, use one of the following methods:
141+
- In the CLI, run the `npm stage approve <stage-id>` command.
142+
- On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
143+
144+
<Note>
145+
146+
**Note:** You will be prompted for 2FA verification regardless of whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com). Once approved, the package is published to the live registry.
147+
148+
</Note>
149+
150+
For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see [Staged publishing][staged-publishing].
151+
113152
[scopes]: about-scopes
114153
[private-pkgs]: about-private-packages
115154
[user-signup]: https://www.npmjs.com/signup
@@ -123,3 +162,4 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
123162
[config-2fa]: /configuring-two-factor-authentication
124163
[creating-token]: /creating-and-viewing-access-tokens
125164
[requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
165+
[staged-publishing]: /staged-publishing

‎content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-scoped-public-packages.mdx‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -77,16 +77,19 @@ npm install /path/to/my-test-package
7777

7878
By default, scoped packages are published with private visibility. To publish a scoped package with public visibility, use `npm publish --access public`.
7979

80-
<Note variant="warning">
80+
There are two ways to publish your package to the npm registry:
8181

82-
**Important:** Publishing to npm requires either:
82+
1. [Direct publishing](#direct-publishing)
83+
2. [Staged publishing](#staged-publishing)
8384

84-
- Two-factor authentication (2FA) enabled on your account, OR
85-
- A granular access token with bypass 2FA enabled
85+
### Direct publishing
8686

87-
For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
87+
To publish directly with `npm publish --access public`, you need either:
8888

89-
</Note>
89+
- Two-factor authentication (2FA) enabled on your account, or
90+
- A granular access token (GAT) with bypass 2FA enabled
91+
92+
For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
9093

9194
1. On the command line, navigate to the root directory of your package.
9295

@@ -112,6 +115,42 @@ For more information, see the npm documentation on [requiring 2FA for package pu
112115

113116
For more information on the `publish` command, see the [CLI documentation][cli-publish].
114117

118+
### Staged publishing
119+
120+
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.
121+
122+
A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
123+
124+
1. On the command line, navigate to the root directory of your package.
125+
126+
```
127+
cd /path/to/my-test-package
128+
```
129+
130+
2. To stage your scoped public package, run:
131+
132+
```
133+
npm stage publish
134+
```
135+
136+
This submits your package to a staging area.
137+
138+
3. To check that your package has been staged, use either of the following methods:
139+
- In the CLI, run `npm stage list <package-name>` to find the staged package and its stage ID.
140+
- On [npmjs.com](https://www.npmjs.com), open the **Staged Packages** tab to review staged packages.
141+
142+
4. To approve and publish the staged package, use one of the following methods:
143+
- In the CLI, run the `npm stage approve <stage-id>` command.
144+
- On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
145+
146+
<Note>
147+
148+
**Note:** You will be prompted for 2FA verification regardless of whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com). Once approved, the package is published to the live registry.
149+
150+
</Note>
151+
152+
For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see [Staged publishing][staged-publishing].
153+
115154
[scopes]: /about-scopes
116155
[user-signup]: https://www.npmjs.com/signup
117156
[create-org]: https://www.npmjs.com/signup?next=/org/create
@@ -125,3 +164,4 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
125164
[config-2fa]: /configuring-two-factor-authentication
126165
[creating-token]: /creating-and-viewing-access-tokens
127166
[requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
167+
[staged-publishing]: /staged-publishing

‎content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -58,16 +58,19 @@ npm install path/to/my-package
5858

5959
## Publishing unscoped public packages
6060

61-
<Note variant="warning">
61+
There are two ways to publish your package to the npm registry:
6262

63-
**Important:** Publishing to npm requires either:
63+
1. [Direct publishing](#direct-publishing)
64+
2. [Staged publishing](#staged-publishing)
6465

65-
- Two-factor authentication (2FA) enabled on your account, OR
66-
- A granular access token with bypass 2FA enabled
66+
### Direct publishing
6767

68-
For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
68+
To publish directly with `npm publish`, you need either:
6969

70-
</Note>
70+
- Two-factor authentication (2FA) enabled on your account, or
71+
- A granular access token (GAT) with bypass 2FA enabled
72+
73+
For more information, see the npm documentation on [requiring 2FA for package publishing](/requiring-2fa-for-package-publishing-and-settings-modification).
7174

7275
1. On the command line, navigate to the root directory of your package.
7376

@@ -91,6 +94,42 @@ For more information, see the npm documentation on [requiring 2FA for package pu
9194

9295
For more information on the `publish` command, see the [CLI documentation][cli-publish].
9396

97+
### Staged publishing
98+
99+
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.
100+
101+
A GAT with bypass 2FA does not bypass the 2FA check during staged package approval.
102+
103+
1. On the command line, navigate to the root directory of your package.
104+
105+
```
106+
cd /path/to/package
107+
```
108+
109+
2. To stage your package, run:
110+
111+
```
112+
npm stage publish
113+
```
114+
115+
This submits your package to a staging area.
116+
117+
3. To check that your package has been staged, use either of the following methods:
118+
- In the CLI, run `npm stage list <package-name>` to find the staged package and its stage ID.
119+
- On [npmjs.com](https://www.npmjs.com), open the **Staged Packages** tab to review staged packages.
120+
121+
4. To approve and publish the staged package, use one of the following methods:
122+
- In the CLI, run the `npm stage approve <stage-id>` command.
123+
- On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
124+
125+
<Note>
126+
127+
**Note:** You will be prompted for 2FA verification regardless of whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com). Once approved, the package is published to the live registry.
128+
129+
</Note>
130+
131+
For the full staged publishing workflow, including reviewing, inspecting, and rejecting staged packages, see [Staged publishing][staged-publishing].
132+
94133
[pkg-viz]: package-scope-access-level-and-visibility
95134
[user-signup]: https://www.npmjs.com/signup
96135
[create-org]: https://www.npmjs.com/signup?next=/org/create
@@ -103,3 +142,4 @@ For more information on the `publish` command, see the [CLI documentation][cli-p
103142
[config-2fa]: /configuring-two-factor-authentication
104143
[creating-token]: /creating-and-viewing-access-tokens
105144
[requiring-2fa]: /requiring-2fa-for-package-publishing-and-settings-modification
145+
[staged-publishing]: /staged-publishing

‎content/packages-and-modules/securing-your-code/staged-publishing.mdx‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: Staged publishing for npm packages
3+
---
4+
5+
Staged publishing adds an approval step before packages go live on the npm registry. Instead of publishing directly with `npm publish`, you can submit packages to a staging area with `npm stage publish`. A maintainer must then review and explicitly approve the staged package — with two-factor authentication (2FA) via the CLI or [npmjs.com](https://www.npmjs.com) — before it becomes publicly available.
6+
7+
Staged publishing is useful when you want an extra review step before a package version becomes available on the registry.
8+
9+
<Note>
10+
11+
**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.
12+
13+
</Note>
14+
15+
## How staged publishing works
16+
17+
Staged publishing has three steps:
18+
19+
1. [Stage a package](#stage-a-package)
20+
2. [Review a staged package](#review-a-staged-package)
21+
3. [Approve a staged package](#approve-a-staged-package)
22+
23+
## Prerequisites
24+
25+
Before using staged publishing, ensure the following:
26+
27+
- You have **publish access** to the package
28+
- The package **already exists** on the npm registry — you cannot stage a brand-new package
29+
- **2FA is enabled** on your npm account
30+
31+
## Stage a package
32+
33+
1. On the command line, navigate to the root directory of your package.
34+
35+
```
36+
cd /path/to/package
37+
```
38+
39+
2. To stage your package, run:
40+
41+
```
42+
npm stage publish
43+
```
44+
45+
This submits your package to a staging area.
46+
47+
<Note>
48+
49+
**Note:** `npm stage publish` does not require 2FA.
50+
51+
</Note>
52+
53+
## Review a staged package
54+
55+
After you stage a package, you can inspect it in the CLI or on [npmjs.com](https://www.npmjs.com).
56+
57+
#### Using the CLI
58+
59+
To list staged packages you have access to:
60+
61+
```
62+
npm stage list [<package-spec>]
63+
```
64+
65+
To view details for a specific staged package:
66+
67+
```
68+
npm stage view <stage-id>
69+
```
70+
71+
To download the staged package tarball for inspection:
72+
73+
```
74+
npm stage download <stage-id>
75+
```
76+
77+
#### Using npmjs.com
78+
79+
Open the **Staged Packages** tab to review staged packages and find the package you want to approve.
80+
81+
<Screenshot
82+
src="/packages-and-modules/securing-your-code/staged-package-tab.png"
83+
alt="Screenshot showing the Staged Packages tab on npmjs.com with staged packages ready for review"
84+
/>
85+
86+
## Approve a staged package
87+
88+
To publish a staged package to the registry, approve it with 2FA.
89+
90+
#### Using the CLI
91+
92+
To approve a staged package and publish it to the live registry:
93+
94+
```
95+
npm stage approve <stage-id>
96+
```
97+
98+
#### Using npmjs.com
99+
100+
On [npmjs.com](https://www.npmjs.com), review the staged package in the **Staged Packages** tab, then click **Approve**.
101+
102+
<Screenshot
103+
src="/packages-and-modules/securing-your-code/staged-package-approve.png"
104+
alt="Screenshot showing a staged package on npmjs.com with the Approve button"
105+
/>
106+
107+
<Note>
108+
109+
**Note:** You will be prompted for 2FA verification whether you approve the package in the CLI or on [npmjs.com](https://www.npmjs.com).
110+
111+
</Note>
112+
113+
## Using staged publishing with trusted publishers
114+
115+
If you use [trusted publishing (OIDC)](/trusted-publishers) from CI/CD, you can use staged publishing to submit a package for review before it goes live. A maintainer must still review and approve the staged package with 2FA.
116+
117+
For more information on configuring trusted publisher permissions, see "[Trusted publishing for npm packages](/trusted-publishers#configuring-allowed-actions)."
118+
119+
## Learn more
120+
121+
- [Trusted publishing for npm packages](./trusted-publishers)
122+
- [Generating provenance statements](./generating-provenance-statements)

0 commit comments

Comments
 (0)