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>

Author: Michael Smith

content/nav.yml

@@ -1788,8 +1788,7 @@
               description: Manage your authentication tokens
             - title: npm trust
               url: /cli/v11/commands/npm-trust
-              description: Manage trusted publishing relationships between packages and CI/CD
-                providers
+              description: Manage trusted publishing relationships between packages and CI/CD providers
             - title: npm undeprecate
               url: /cli/v11/commands/npm-undeprecate
               description: Undeprecate a version of a package

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

@@ -83,7 +83,7 @@ For more information, see the npm documentation on [requiring 2FA for package pu
 
    <Note>
 
-   **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]."
+   **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]."
 
    </Note>
 

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

@@ -22,14 +22,15 @@ Trusted publishing currently supports:
 
 - [GitHub Actions](https://github.com/features/actions) (GitHub-hosted runners)
 - [GitLab CI/CD Pipelines](https://docs.gitlab.com/ci/pipelines/) (GitLab.com shared runners)
+- [CircleCI](https://circleci.com/) (CircleCI cloud)
 
 Self-hosted runners are not currently supported but are planned for future releases.
 
 ## Configuring trusted publishing
 
 ### Step 1: Add a trusted publisher on npmjs.com
 
-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.
+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.
 
 <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" />
 
@@ -59,6 +60,18 @@ Configure the following fields:
 
 <Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-gitlab.png" alt="Screenshot of GitLab CI/CD trusted publisher configuration form" />
 
+#### For CircleCI
+
+Configure the following fields:
+
+- **Organization ID** (required): Your CircleCI organization ID (UUID format). You may find it from your CircleCI Organization Settings Overview page.
+- **Project ID** (required): Your CircleCI project ID (UUID format). You may find it from your CircleCI Project Settings Overview page.
+- **Pipeline definition ID** (required): The pipeline definition ID (UUID format). You may find it from your CircleCI Project Settings under Project Setup page.
+- **VCS origin** (required): The VCS origin URL for your project (e.g., `github.com/myorg/myrepo`)
+- **Context IDs** (optional): Restrict publishing to jobs using specific CircleCI contexts. You may find them from your CircleCI Organization Settings Contexts.
+
+<Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-circleci.png" alt="Screenshot of CircleCI trusted publisher configuration form" />
+
 <Note>
 
 **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
 
 </Note>
 
+#### CircleCI configuration
+
+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:
+
+```yaml
+version: 2.1
+
+jobs:
+  publish:
+    docker:
+      - image: cimg/node:22.14
+    steps:
+      - checkout
+      - run:
+          name: Install dependencies
+          command: npm ci
+      - run:
+          name: Run tests
+          command: npm test
+      - run:
+          name: Build
+          command: npm run build --if-present
+      - run:
+          name: Publish to npm with OIDC
+          command: |
+            export NPM_ID_TOKEN=$(circleci run oidc get --claims '{"aud": "npm:registry.npmjs.org"}')
+            npm publish
+
+workflows:
+  publish:
+    jobs:
+      - publish:
+          filters:
+            tags:
+              only: /^v.*/
+            branches:
+              ignore: /.*/
+```
+
+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/).
+
 ### Managing trusted publisher configurations
 
 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.
 
 ## Automatic provenance generation
 
-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.
+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.
+
+<Note>
+
+**Note:** Provenance generation is not currently supported for CircleCI. Packages published via CircleCI trusted publishing will not include provenance attestations.
+
+</Note>
 
 <Screenshot src="/packages-and-modules/securing-your-code/trusted-publisher-provenance.png" alt="Screenshot showing provenance badge/information on a package page" />
 
@@ -264,7 +324,7 @@ Consider implementing these additional security practices:
 
 ## Troubleshooting
 
-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.
+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.
 
 <Note>
 
@@ -292,4 +352,5 @@ We intend to expand trusted publishing support to additional CI/CD providers and
 - [OpenSSF Trusted Publishers specification](https://repos.openssf.org/trusted-publishers-for-all-package-repositories)
 - [GitHub Actions OIDC documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
 - [GitLab CI/CD OIDC documentation](https://docs.gitlab.com/ee/ci/cloud_services/)
+- [CircleCI OIDC documentation](https://circleci.com/docs/openid-connect-tokens/)
 - [API documentation for exchanging OIDC ID token for npm registry token](https://api-docs.npmjs.com/#tag/registry.npmjs.org/operation/exchangeOidcToken)