@cryptotaxi247 / documentation-1 / commits / b8fe40f

docs: adds circleci documentation (#1873)

This pull request updates the npm documentation to add support for CircleCI as a trusted publisher, alongside GitHub Actions and GitLab CI/CD. It provides instructions and configuration details for setting up trusted publishing with CircleCI, clarifies the provenance generation limitations for CircleCI, and updates troubleshooting and reference sections accordingly. --------- Co-authored-by: Di Hei <dhei@github.com>

Michael Smith committed Mar 4, 2026 at 11:57 UTC b8fe40fc5a6053b00b3032bca9fc786e1468e8f9
5 files changed +66 -6
content/nav.yml
+1 -2
@@ -1788,8 +1788,7 @@
1788 description: Manage your authentication tokens
1789 - title: npm trust
1790 url: /cli/v11/commands/npm-trust
1791 - description: Manage trusted publishing relationships between packages and CI/CD
1792 - providers
1791 + description: Manage trusted publishing relationships between packages and CI/CD providers
1792 - title: npm undeprecate
1793 url: /cli/v11/commands/npm-undeprecate
1794 description: Undeprecate a version of a package
content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx
+1 -1
@@ -83,7 +83,7 @@ For more information, see the npm documentation on [requiring 2FA for package pu
83
84 <Note>
85
86 - **Note:** If you use GitHub Actions or GitLab CI/CD to publish your packages, consider using [trusted publishing](/trusted-publishers) for enhanced security. Trusted publishing automatically generates provenance information and eliminates the need for access tokens in your CI/CD workflows. For more information, see "[Generating provenance statements][provenance-how-to]."
86 + **Note:** If you use GitHub Actions, GitLab CI/CD, or CircleCI to publish your packages, consider using [trusted publishing](/trusted-publishers) for enhanced security. Trusted publishing eliminates the need for access tokens in your CI/CD workflows. For GitHub Actions and GitLab CI/CD, it also automatically generates provenance information. For more information, see "[Generating provenance statements][provenance-how-to]."
87
88 </Note>
89
content/packages-and-modules/securing-your-code/trusted-publishers.mdx
+64 -3
@@ -22,6 +22,7 @@ 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 +- [CircleCI](https://circleci.com/) (CircleCI cloud)
26
27 Self-hosted runners are not currently supported but are planned for future releases.
28
@@ -29,7 +30,7 @@ Self-hosted runners are not currently supported but are planned for future relea
30
31 ### Step 1: Add a trusted publisher on npmjs.com
32
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 +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 the GitHub Actions, GitLab CI/CD, or CircleCI button.
34
35 <Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher.png" alt="Screenshot showing the Trusted Publisher section with Select your publisher label and provider buttons" />
36
@@ -59,6 +60,18 @@ Configure the following fields:
60
61 <Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-gitlab.png" alt="Screenshot of GitLab CI/CD trusted publisher configuration form" />
62
63 +#### For CircleCI
64 +
65 +Configure the following fields:
66 +
67 +- **Organization ID** (required): Your CircleCI organization ID (UUID format). You may find it from your CircleCI Organization Settings Overview page.
68 +- **Project ID** (required): Your CircleCI project ID (UUID format). You may find it from your CircleCI Project Settings Overview page.
69 +- **Pipeline definition ID** (required): The pipeline definition ID (UUID format). You may find it from your CircleCI Project Settings under Project Setup page.
70 +- **VCS origin** (required): The VCS origin URL for your project (e.g., `github.com/myorg/myrepo`)
71 +- **Context IDs** (optional): Restrict publishing to jobs using specific CircleCI contexts. You may find them from your CircleCI Organization Settings Contexts.
72 +
73 +<Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-circleci.png" alt="Screenshot of CircleCI trusted publisher configuration form" />
74 +
75 <Note>
76
77 **Note:** Each package can only have one trusted publisher configured at a time.
@@ -145,6 +158,47 @@ The `id_tokens` configuration tells GitLab to generate an OIDC token for npm. Le
158
159 </Note>
160
161 +#### CircleCI configuration
162 +
163 +Set the `NPM_ID_TOKEN` environment variable with an OIDC token from CircleCI, and npm CLI handles the token exchange automatically. Here's a complete example:
164 +
165 +```yaml
166 +version: 2.1
167 +
168 +jobs:
169 + publish:
170 + docker:
171 + - image: cimg/node:22.14
172 + steps:
173 + - checkout
174 + - run:
175 + name: Install dependencies
176 + command: npm ci
177 + - run:
178 + name: Run tests
179 + command: npm test
180 + - run:
181 + name: Build
182 + command: npm run build --if-present
183 + - run:
184 + name: Publish to npm with OIDC
185 + command: |
186 + export NPM_ID_TOKEN=$(circleci run oidc get --claims '{"aud": "npm:registry.npmjs.org"}')
187 + npm publish
188 +
189 +workflows:
190 + publish:
191 + jobs:
192 + - publish:
193 + filters:
194 + tags:
195 + only: /^v.*/
196 + branches:
197 + ignore: /.*/
198 +```
199 +
200 +The `circleci run oidc get` command retrieves an OIDC token from CircleCI. When `NPM_ID_TOKEN` is set, the npm CLI automatically exchanges it for a short-lived publish token. Learn more in [CircleCI's OIDC documentation](https://circleci.com/docs/openid-connect-tokens/).
201 +
202 ### Managing trusted publisher configurations
203
204 You can modify or remove your trusted publisher configuration at any time through your package settings on [npmjs.com](https://npmjs.com) → Packages → YOUR_PACKAGE → Settings → Trusted publishing. 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.
@@ -177,7 +231,13 @@ This ensures a smooth transition without disrupting your release process.
231
232 ## Automatic provenance generation
233
180 -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.
234 +When you publish using trusted publishing from GitHub Actions or GitLab CI/CD, 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.
235 +
236 +<Note>
237 +
238 +**Note:** Provenance generation is not currently supported for CircleCI. Packages published via CircleCI trusted publishing will not include provenance attestations.
239 +
240 +</Note>
241
242 <Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-provenance.png" alt="Screenshot showing provenance badge/information on a package page" />
243
@@ -264,7 +324,7 @@ Consider implementing these additional security practices:
324
325 ## Troubleshooting
326
267 -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. All fields are 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.
327 +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. All fields are case-sensitive and must be exact. Also ensure you're using GitHub-hosted runners, GitLab.com shared runners, or CircleCI cloud, as self-hosted runners are not currently supported. For GitHub Actions specifically, check that the `id-token: write` permission is set in your workflow. For CircleCI, verify that your Organization ID, Project ID, and Pipeline definition ID match your CircleCI configuration.
328
329 <Note>
330
@@ -292,4 +352,5 @@ We intend to expand trusted publishing support to additional CI/CD providers and
352 - [OpenSSF Trusted Publishers specification](https://repos.openssf.org/trusted-publishers-for-all-package-repositories)
353 - [GitHub Actions OIDC documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
354 - [GitLab CI/CD OIDC documentation](https://docs.gitlab.com/ee/ci/cloud_services/)
355 +- [CircleCI OIDC documentation](https://circleci.com/docs/openid-connect-tokens/)
356 - [API documentation for exchanging OIDC ID token for npm registry token](https://api-docs.npmjs.com/#tag/registry.npmjs.org/operation/exchangeOidcToken)
static/packages-and-modules/securing-your-code/trusted-publisher-circleci.png
Binary files /dev/null and b/static/packages-and-modules/securing-your-code/trusted-publisher-circleci.png differ
static/packages-and-modules/securing-your-code/trusted-publisher.png
Binary files a/static/packages-and-modules/securing-your-code/trusted-publisher.png and b/static/packages-and-modules/securing-your-code/trusted-publisher.png differ