Skip to content

Commit 1cc214d

Browse files
leobalterleobalter
authored
Add docs for trusted publishing
1 parent 0cef75b commit 1cc214d

File tree

1 file changed

+266
-0
lines changed

1 file changed

+266
-0
lines changed

‎content/packages-and-modules/securing-your-code/trusted-publishers.mdx‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
---
2+
title: Trusted publishing for npm packages
3+
---
4+
5+
Trusted publishing allows you to publish npm packages directly from your CI/CD workflows using [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) authentication, eliminating the need for long-lived npm tokens. This feature implements the [Trusted Publishers standard](https://repos.openssf.org/trusted-publishers-for-all-package-repositories) from the Open Source Security Foundation (OpenSSF), joining a growing ecosystem including [PyPI](https://docs.pypi.org/trusted-publishers/), [RubyGems](https://guides.rubygems.org/trusted-publishing/), and other major package registries in offering this security enhancement.
6+
7+
<Note>
8+
9+
**Note:** Trusted publishing requires [npm CLI](https://docs.npmjs.com/cli/v11) version 11.5.0 or later.
10+
11+
</Note>
12+
13+
## How trusted publishing works
14+
15+
Trusted publishing creates a trust relationship between npm and your CI/CD provider using OIDC. When you configure a trusted publisher for your package, npm will accept publishes from the specific workflow you've authorized, in addition to traditional authentication methods like npm tokens and manual publishes. The npm CLI automatically detects OIDC environments and uses them for authentication before falling back to traditional tokens.
16+
17+
This approach eliminates the security risks associated with long-lived write tokens, which can be compromised, accidentally exposed in logs, or require manual rotation. Instead, each publish uses short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused.
18+
19+
## Supported CI/CD providers
20+
21+
Trusted publishing currently supports:
22+
23+
- [GitHub Actions](https://github.com/features/actions) (GitHub-hosted runners)
24+
- [GitLab CI/CD Pipelines](https://docs.gitlab.com/ci/pipelines/) (GitLab.com shared runners)
25+
26+
Self-hosted runners are not currently supported but are planned for future releases.
27+
28+
## Configuring trusted publishing
29+
30+
### Step 1: Add a trusted publisher on npmjs.com
31+
32+
Navigate to your package settings on [npmjs.com](https://www.npmjs.com) and find the "__Trusted Publisher__" section. Under "__Select your publisher__", choose your CI/CD provider by clicking either the GitHub Actions or GitLab CI/CD button.
33+
34+
<!-- TODO: Add screenshot of the Trusted Publisher section with "Select your publisher" label and provider buttons -->
35+
36+
#### For GitHub Actions
37+
38+
Configure the following fields:
39+
40+
- **Organization or user** (required): Your GitHub username or organization name
41+
- **Repository** (required): Your repository name
42+
- **Workflow filename** (required): The filename of your workflow (e.g., `publish.yml`)
43+
- Enter only the filename, not the full path
44+
- Must include the `.yml` or `.yaml` extension
45+
- The workflow file must exist in `.github/workflows/` in your repository
46+
- **Environment name** (optional): If using [GitHub environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) for deployment protection
47+
48+
<!-- TODO: Add screenshot of GitHub Actions trusted publisher configuration form -->
49+
50+
#### For GitLab CI/CD
51+
52+
Configure the following fields:
53+
54+
- **Namespace** (required): Your GitLab username or group name
55+
- **Project name** (required): Your project name
56+
- **Top-level CI file path** (required): The path to your CI file (e.g., `.gitlab-ci.yml`)
57+
- Must include the `.yml` extension
58+
- **Environment name** (optional): If using [GitLab environments](https://docs.gitlab.com/ee/ci/environments/)
59+
60+
<!-- TODO: Add screenshot of GitLab CI/CD trusted publisher configuration form -->
61+
62+
<Note>
63+
64+
**Note:** Each package can only have one trusted publisher configured at a time.
65+
66+
</Note>
67+
68+
### Step 2: Configure your CI/CD workflow
69+
70+
#### GitHub Actions configuration
71+
72+
Add the required OIDC permissions to your workflow. Here's a complete example:
73+
74+
```yaml
75+
name: Publish Package
76+
77+
on:
78+
push:
79+
tags:
80+
- 'v*'
81+
82+
permissions:
83+
id-token: write # Required for OIDC
84+
contents: read
85+
86+
jobs:
87+
publish:
88+
runs-on: ubuntu-latest
89+
steps:
90+
- uses: actions/checkout@v4
91+
92+
- uses: actions/setup-node@v4
93+
with:
94+
node-version: '20'
95+
registry-url: 'https://registry.npmjs.org'
96+
97+
# Ensure npm 11.5.0 or later is installed
98+
- name: Update npm
99+
run: npm install -g npm@latest
100+
- run: npm ci
101+
- run: npm run build --if-present
102+
- run: npm test
103+
- run: npm publish
104+
```
105+
106+
The critical requirement is the `id-token: write` permission, which allows GitHub Actions to generate OIDC tokens. Learn more in [GitHub's OIDC documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect).
107+
108+
#### GitLab CI/CD configuration
109+
110+
Configure the OIDC ID token in your pipeline:
111+
112+
```yaml
113+
stages:
114+
- test
115+
- build
116+
- publish
117+
118+
variables:
119+
NODE_VERSION: '20'
120+
121+
id_tokens:
122+
NPM_ID_TOKEN:
123+
aud: "npm:registry.npmjs.org"
124+
125+
test:
126+
stage: test
127+
image: node:${NODE_VERSION}
128+
script:
129+
- npm ci
130+
- npm test
131+
132+
publish:
133+
stage: publish
134+
image: node:${NODE_VERSION}
135+
script:
136+
# Ensure npm 11.5.0 or later is installed
137+
- npm install -g npm@latest
138+
- npm ci
139+
- npm run build --if-present
140+
- npm publish
141+
only:
142+
- tags
143+
```
144+
145+
The `id_tokens` configuration tells GitLab to generate an OIDC token for npm. Learn more in [GitLab's OIDC documentation](https://docs.gitlab.com/ee/ci/cloud_services/).
146+
147+
### Managing trusted publisher configurations
148+
149+
You can modify or remove your trusted publisher configuration at any time through your package settings on [npmjs.com](https://npmjs.com). Each package can only have one trusted publisher connection at a time, but this connection can be edited or deleted as needed. To change providers (for example, switching from GitHub Actions to GitLab CI/CD), simply edit your existing configuration and select the new provider. The change takes effect immediately for future publishes. To remove trusted publishing entirely and return to token-based authentication, delete the trusted publisher configuration from your package settings.
150+
151+
## Automatic provenance generation
152+
153+
When you publish using trusted publishing, npm automatically generates and publishes [provenance attestations](./generating-provenance-statements) for your package. This happens by default—you don't need to add the `--provenance` flag to your publish command.
154+
155+
<!-- TODO: Add screenshot showing provenance badge/information on a package page -->
156+
157+
Provenance provides cryptographic proof of where and how your package was built, allowing users to verify its authenticity. This automatic generation only applies when all of these conditions are met:
158+
159+
- Publishing via trusted publishing (OIDC)
160+
- Publishing from a public repository
161+
- Publishing a public package
162+
163+
<Note>
164+
165+
**Note:** Provenance generation is [not supported for private repositories](https://github.blog/changelog/2023-07-25-publishing-with-npm-provenance-from-private-source-repositories-is-no-longer-supported/), even when publishing public packages.
166+
167+
</Note>
168+
169+
### Disabling provenance generation
170+
171+
While we strongly recommend keeping provenance enabled, you can disable it if needed. Set the `provenance` option to `false` in any of these ways:
172+
173+
**Using environment variable:**
174+
```bash
175+
NPM_CONFIG_PROVENANCE=false npm publish
176+
```
177+
178+
**In your `.npmrc` file:**
179+
```ini
180+
provenance=false
181+
```
182+
183+
**In your `package.json`:**
184+
```json
185+
{
186+
"publishConfig": {
187+
"provenance": false
188+
}
189+
}
190+
```
191+
192+
## Security best practices
193+
194+
### Prefer trusted publishing over tokens
195+
196+
When trusted publishing is available for your workflow, always prefer it over long-lived tokens. Traditional npm tokens pose several security risks:
197+
198+
- They can be accidentally exposed in CI logs or configuration files
199+
- They require manual rotation and management
200+
- If compromised, they provide persistent access until revoked
201+
- They often have broader permissions than necessary
202+
203+
Trusted publishing eliminates these risks by using short-lived, workflow-specific credentials that are automatically managed and cannot be extracted.
204+
205+
### Handling private dependencies
206+
207+
While trusted publishing handles the publish operation, you may still need authentication for installing private npm dependencies. For this scenario, we recommend:
208+
209+
```yaml
210+
# GitHub Actions example
211+
- uses: actions/setup-node@v4
212+
with:
213+
node-version: '20'
214+
registry-url: 'https://registry.npmjs.org'
215+
216+
# Ensure npm 11.5.0 or later for trusted publishing
217+
- run: npm install -g npm@latest
218+
219+
# Use a read-only token for installing dependencies
220+
- run: npm ci
221+
env:
222+
NODE_AUTH_TOKEN: ${{ secrets.NPM_READ_TOKEN }}
223+
224+
# Publish uses OIDC - no token needed
225+
- run: npm publish
226+
```
227+
228+
Always use [read-only granular access tokens](/integrations/integrating-npm-with-external-services/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website) for installing dependencies. This limits potential damage if the token is ever compromised.
229+
230+
### Additional security measures
231+
232+
Consider implementing these additional security practices:
233+
234+
- Use [deployment environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) to add approval requirements
235+
- Enable [tag protection rules](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules) to control who can create release tags
236+
- Regularly audit your trusted publisher configurations
237+
- Remove any unused publish tokens from your npm account
238+
239+
## Troubleshooting
240+
241+
If you encounter an "Unable to authenticate" error when publishing, first verify that the workflow filename matches exactly what you configured on [npmjs.com](https://npmjs.com), including the `.yml` extension. The filename is case-sensitive and must be exact. Also ensure you're using GitHub-hosted runners or GitLab.com shared runners, as self-hosted runners are not currently supported. For GitHub Actions specifically, check that the `id-token: write` permission is set in your workflow.
242+
243+
<Note>
244+
245+
**Note:** npm does not verify your trusted publisher configuration when you save it. Double-check that your repository, workflow filename, and other details are correct, as errors will only appear when you attempt to publish.
246+
247+
</Note>
248+
249+
If your package has private dependencies and `npm install` or `npm ci` is failing with authentication errors, remember that trusted publishing only applies to the `npm publish` command. You'll still need to provide a read-only token for installing private packages as shown in the examples above.
250+
251+
For packages in private repositories, provenance will not be generated even though you're using trusted publishing. This is a [known limitation](https://github.blog/changelog/2023-07-25-publishing-with-npm-provenance-from-private-source-repositories-is-no-longer-supported/) that applies regardless of whether your package itself is public or private.
252+
253+
## Limitations and future improvements
254+
255+
Trusted publishing currently supports only cloud-hosted runners. Support for self-hosted runners is intended for a future release. Each package can only have one trusted publisher configured at a time, though you can update this configuration as needed.
256+
257+
OIDC authentication is currently limited to the publish operation. Other npm commands such as `install`, `view`, or `access` still require traditional authentication methods. The `npm whoami` command will not reflect OIDC authentication status since the authentication occurs only during the publish operation.
258+
259+
We intend to expand trusted publishing support to additional CI/CD providers and enhance the feature based on community feedback.
260+
261+
## Learn more
262+
263+
- [About npm provenance](./generating-provenance-statements)
264+
- [OpenSSF Trusted Publishers specification](https://repos.openssf.org/trusted-publishers-for-all-package-repositories)
265+
- [GitHub Actions OIDC documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
266+
- [GitLab CI/CD OIDC documentation](https://docs.gitlab.com/ee/ci/cloud_services/)

0 commit comments

Comments
 (0)