diff --git a/content/nav.yml b/content/nav.yml index af33cefa693..40a673aa805 100644 --- a/content/nav.yml +++ b/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 diff --git a/content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx b/content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx index 709d591f3b1..608b53385d7 100644 --- a/content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx +++ b/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:** 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]." diff --git a/content/packages-and-modules/securing-your-code/trusted-publishers.mdx b/content/packages-and-modules/securing-your-code/trusted-publishers.mdx index 1c13d48448d..cb561f89309 100644 --- a/content/packages-and-modules/securing-your-code/trusted-publishers.mdx +++ b/content/packages-and-modules/securing-your-code/trusted-publishers.mdx @@ -22,6 +22,7 @@ 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. @@ -29,7 +30,7 @@ Self-hosted runners are not currently supported but are planned for future relea ### 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. @@ -59,6 +60,18 @@ Configure the following fields: +#### 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. + + + **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 +#### 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:** Provenance generation is not currently supported for CircleCI. Packages published via CircleCI trusted publishing will not include provenance attestations. + + @@ -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. @@ -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) diff --git a/static/packages-and-modules/securing-your-code/trusted-publisher-circleci.png b/static/packages-and-modules/securing-your-code/trusted-publisher-circleci.png new file mode 100644 index 00000000000..a95f932abbf Binary files /dev/null and b/static/packages-and-modules/securing-your-code/trusted-publisher-circleci.png differ diff --git a/static/packages-and-modules/securing-your-code/trusted-publisher.png b/static/packages-and-modules/securing-your-code/trusted-publisher.png index e74c9d24986..2db62bb11e4 100644 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