From 6633a8a6727d1879b594fdd4e774e8b3b7004c28 Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Wed, 22 Apr 2026 16:46:10 +0530 Subject: [PATCH 1/3] Add documentation for publishing to npm with Trusted Publisher (OIDC) --- README.md | 1 + docs/advanced-usage.md | 47 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/README.md b/README.md index aad5a82a0..715026def 100644 --- a/README.md +++ b/README.md @@ -249,6 +249,7 @@ If the runner is not able to access github.com, any Nodejs versions requested du - [Publishing to npmjs and GPR with npm](docs/advanced-usage.md#publish-to-npmjs-and-gpr-with-npm) - [Publishing to npmjs and GPR with yarn](docs/advanced-usage.md#publish-to-npmjs-and-gpr-with-yarn) - [Using private packages](docs/advanced-usage.md#use-private-packages) + - [Publishing to npm with Trusted Publisher (OIDC)](docs/advanced-usage.md#publishing-to-npm-with-trusted-publisher-oidc) - [Using private mirror](docs/advanced-usage.md#use-private-mirror) ## Recommended permissions diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 19f869f00..4aa84c190 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -475,6 +475,53 @@ To access private GitHub Packages within the same organization, go to "Manage Ac Please refer to the [Ensuring workflow access to your package - Configuring a package's access control and visibility](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#ensuring-workflow-access-to-your-package) for more details. +## Publishing to npm with Trusted Publisher (OIDC) + +Npm supports Trusted Publishers, enabling packages to be published from GitHub Actions using OpenID Connect (OIDC) instead of long-lived npm tokens. This improves security by replacing static credentials with short-lived tokens, reducing the risk of credential leakage and simplifying authentication in CI/CD workflows. + +### Requirements + +Trusted publishing requires a compatible npm version: + +* **npm ≥ 11.5.1 (required)** +* **Node.js 24 or newer (recommended)** — includes a compatible npm version by default + +> If npm is below 11.5.1, publishing will fail even if OIDC permissions are correctly configured. + +You must also configure a **Trusted Publisher** in npm for your package/scope that matches your GitHub repository and workflow (and optional environment, if used). + +### Example workflow + +```yaml + permissions: + contents: read + id-token: write + + steps: + - uses: actions/checkout@v6 + + - uses: actions/setup-node@v6 + with: + node-version: '24' + registry-url: 'https://registry.npmjs.org' + + - run: npm ci + - run: npm run build --if-present + - run: npm publish +``` + +### Important + +* `id-token: write` is required for OIDC authentication +* `contents: read` is required for repository access +* If a Trusted Publisher is configured with a GitHub Actions **environment**, it must also be set on the job (e.g. `environment: release`). + +OIDC authentication is handled automatically via GitHub’s identity token. + +> **Note**: If the Trusted Publisher configuration (GitHub owner/repo/workflow file, and optional environment) does not match the workflow run identity exactly, publishing may fail with **E404 Not Found** even if the package exists on npm. + +For more details, see the [npm Trusted Publishers documentation](https://docs.npmjs.com/trusted-publishers) and the [GitHub Actions OpenID Connect (OIDC) overview](https://docs.github.com/en/actions/concepts/security/openid-connect). + ## Use private mirror It is possible to use a private mirror hosting Node.js binaries. This mirror must be a full mirror of the official Node.js distribution. From 7ff57b903dac904d5827b3109ce4b74cb47ef642 Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Wed, 22 Apr 2026 16:56:54 +0530 Subject: [PATCH 2/3] Fix typos in documentation for publishing to npm with Trusted Publisher (OIDC) --- docs/advanced-usage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 4aa84c190..3620768d4 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -477,7 +477,7 @@ Please refer to the [Ensuring workflow access to your package - Configuring a pa ## Publishing to npm with Trusted Publisher (OIDC) -Npm supports Trusted Publishers, enabling packages to be published from GitHub Actions using OpenID Connect (OIDC) instead of long-lived npm tokens. This improves security by replacing static credentials with short-lived tokens, reducing the risk of credential leakage and simplifying authentication in CI/CD workflows. +npm supports Trusted Publishers, enabling packages to be published from GitHub Actions using OpenID Connect (OIDC) instead of long-lived npm tokens. This improves security by replacing static credentials with short-lived tokens, reducing the risk of credential leakage and simplifying authentication in CI/CD workflows. ### Requirements @@ -516,7 +516,7 @@ You must also configure a **Trusted Publisher** in npm for your package/scope th * `contents: read` is required for repository access * If a Trusted Publisher is configured with a GitHub Actions **environment**, it must also be set on the job (e.g. `environment: release`). -OIDC authentication is handled automatically via GitHub’s identity token. +OIDC authentication is handled automatically via GitHub's identity token. > **Note**: If the Trusted Publisher configuration (GitHub owner/repo/workflow file, and optional environment) does not match the workflow run identity exactly, publishing may fail with **E404 Not Found** even if the package exists on npm. From d77de13a550b6221640b7cd0260bf9e863894159 Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Thu, 23 Apr 2026 08:09:21 +0530 Subject: [PATCH 3/3] Clarify OIDC requirements in advanced usage documentation --- docs/advanced-usage.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 3620768d4..2671a6ad3 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -495,7 +495,7 @@ You must also configure a **Trusted Publisher** in npm for your package/scope th ```yaml permissions: contents: read - id-token: write + id-token: write # Required for OIDC steps: - uses: actions/checkout@v6 @@ -510,14 +510,6 @@ You must also configure a **Trusted Publisher** in npm for your package/scope th - run: npm publish ``` -### Important - -* `id-token: write` is required for OIDC authentication -* `contents: read` is required for repository access -* If a Trusted Publisher is configured with a GitHub Actions **environment**, it must also be set on the job (e.g. `environment: release`). - -OIDC authentication is handled automatically via GitHub's identity token. - > **Note**: If the Trusted Publisher configuration (GitHub owner/repo/workflow file, and optional environment) does not match the workflow run identity exactly, publishing may fail with **E404 Not Found** even if the package exists on npm. For more details, see the [npm Trusted Publishers documentation](https://docs.npmjs.com/trusted-publishers) and the [GitHub Actions OpenID Connect (OIDC) overview](https://docs.github.com/en/actions/concepts/security/openid-connect).