From c5c7f3a0e56ea8d783039af9e0fed54105bcad2f Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Tue, 21 Apr 2026 08:02:33 +0530 Subject: [PATCH 1/7] Add documentation for publishing to npm with Trusted Publisher (OIDC) --- README.md | 1 + docs/advanced-usage.md | 128 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+) diff --git a/README.md b/README.md index aad5a82a0..ff13ae4dc 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..f01f602fa 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -475,6 +475,134 @@ 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](https://docs.npmjs.com/trusted-publishers), which allow publishing packages from GitHub Actions using OpenID Connect (OIDC) instead of long-lived tokens. + +Trusted publishing improves security by eliminating long-lived npm tokens and using short-lived OIDC credentials. This approach reduces the risk of credential leakage and simplifies 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 +name: Publish to npm + +on: + push: + tags: + - 'v*' + +jobs: + publish: + runs-on: ubuntu-latest + 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 --access public +``` + +### 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. + +> ⚠️ 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. + +### How authentication works + +When running in a supported CI environment, npm: + +* Detects the OIDC environment +* Attempts OIDC-based authentication +* Falls back to token-based authentication if OIDC is not available + +### Authentication note + +`NODE_AUTH_TOKEN` is **not required** for Trusted Publisher (OIDC). + +* If present, it may interfere with OIDC by causing npm to attempt token-based authentication instead. +* Recommended: **Do not set `NODE_AUTH_TOKEN`** (and consider unsetting `NODE_AUTH_TOKEN`, `NPM_TOKEN`, and `NPM_AUTH_TOKEN`) when using OIDC to avoid unexpected conflicts. + + +### Compatibility note + +* OIDC publishing depends on npm support (≥ 11.5.1). +* Using older Node.js versions (with older npm) can result in authentication failures. +* Clearing or unsetting `NODE_AUTH_TOKEN` **does not resolve failures caused by incompatible npm versions**. +* If you need to use an older Node.js version, upgrade npm before publishing (example): + + ```yaml + - uses: actions/setup-node@v6 + with: + node-version: 20 + registry-url: 'https://registry.npmjs.org/' + + # Ensure npm 11.5.1 or later is installed + - run: npm install -g npm@latest + - run: npm publish --access public + ``` +### Limitations + +* Trusted publishing is supported only on GitHub-hosted runners. +* Self-hosted runners are not currently supported but are planned for future releases. + +### FAQ + +**Q: Do I need to set `NODE_AUTH_TOKEN` for Trusted Publisher (OIDC)?** + +No. OIDC replaces the need for tokens entirely. + +**Q: My package exists on npm, but `npm publish` fails with `E404 Not Found`. Why?** + +This usually indicates that the Trusted Publisher configuration does not exactly match the workflow run identity (repository, workflow filename, or environment), or that the workflow does not have permission to publish to the package or scope. + +All fields are case-sensitive and must match exactly. + + + +### Troubleshooting + +* Verify npm version: +```yaml +npm -v +``` + +Ensure it is ≥ 11.5.1 +* Ensure `id-token: write` permission is set +* Check that the workflow filename matches exactly (including `.yml`) +* Ensure the repository and organization match `npm` configuration +* Ensure `repository.url` in `package.json` matches your GitHub repository + +### References + +* https://docs.npmjs.com/trusted-publishers +* https://docs.github.com/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-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 f78491ce657a0bf88ab7baa8cde4bd509d40d01e Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Tue, 21 Apr 2026 10:41:18 +0530 Subject: [PATCH 2/7] Fix formatting for Trusted Publisher (OIDC) documentation link in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ff13ae4dc..715026def 100644 --- a/README.md +++ b/README.md @@ -249,7 +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) + - [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 From 4ba0873c919f4d316e1f2b9bccadaadbed2f1296 Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Tue, 21 Apr 2026 10:55:52 +0530 Subject: [PATCH 3/7] Fix formatting and punctuation in Trusted Publisher (OIDC) documentation --- docs/advanced-usage.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index f01f602fa..a33efee7b 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -479,7 +479,7 @@ Please refer to the [Ensuring workflow access to your package - Configuring a pa npm supports [Trusted Publishers](https://docs.npmjs.com/trusted-publishers), which allow publishing packages from GitHub Actions using OpenID Connect (OIDC) instead of long-lived tokens. -Trusted publishing improves security by eliminating long-lived npm tokens and using short-lived OIDC credentials. This approach reduces the risk of credential leakage and simplifies authentication in CI/CD workflows +Trusted publishing improves security by eliminating long-lived npm tokens and using short-lived OIDC credentials. This approach reduces the risk of credential leakage and simplifies authentication in CI/CD workflows. ### Requirements @@ -563,7 +563,7 @@ When running in a supported CI environment, npm: registry-url: 'https://registry.npmjs.org/' # Ensure npm 11.5.1 or later is installed - - run: npm install -g npm@latest + - run: npm install -g npm@latest - run: npm publish --access public ``` ### Limitations @@ -588,9 +588,8 @@ All fields are case-sensitive and must match exactly. ### Troubleshooting * Verify npm version: -```yaml -npm -v -``` + ```sh + npm -v Ensure it is ≥ 11.5.1 * Ensure `id-token: write` permission is set @@ -600,8 +599,8 @@ Ensure it is ≥ 11.5.1 ### References -* https://docs.npmjs.com/trusted-publishers -* https://docs.github.com/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect +* https://docs.npmjs.com/trusted-publishers +* https://docs.github.com/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect ## Use private mirror From 36cdbf4fe3372756b8e57fc5be60b941c04453ce Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Wed, 22 Apr 2026 11:37:56 +0530 Subject: [PATCH 4/7] Remove outdated OIDC authentication details and streamline Trusted Publisher documentation --- docs/advanced-usage.md | 73 ------------------------------------------ 1 file changed, 73 deletions(-) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index a33efee7b..7aa87c5e9 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -496,16 +496,6 @@ You must also configure a **Trusted Publisher** in npm for your package/scope th ### Example workflow ```yaml -name: Publish to npm - -on: - push: - tags: - - 'v*' - -jobs: - publish: - runs-on: ubuntu-latest permissions: contents: read id-token: write @@ -533,69 +523,6 @@ OIDC authentication is handled automatically via GitHub’s identity token. > ⚠️ 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. -### How authentication works - -When running in a supported CI environment, npm: - -* Detects the OIDC environment -* Attempts OIDC-based authentication -* Falls back to token-based authentication if OIDC is not available - -### Authentication note - -`NODE_AUTH_TOKEN` is **not required** for Trusted Publisher (OIDC). - -* If present, it may interfere with OIDC by causing npm to attempt token-based authentication instead. -* Recommended: **Do not set `NODE_AUTH_TOKEN`** (and consider unsetting `NODE_AUTH_TOKEN`, `NPM_TOKEN`, and `NPM_AUTH_TOKEN`) when using OIDC to avoid unexpected conflicts. - - -### Compatibility note - -* OIDC publishing depends on npm support (≥ 11.5.1). -* Using older Node.js versions (with older npm) can result in authentication failures. -* Clearing or unsetting `NODE_AUTH_TOKEN` **does not resolve failures caused by incompatible npm versions**. -* If you need to use an older Node.js version, upgrade npm before publishing (example): - - ```yaml - - uses: actions/setup-node@v6 - with: - node-version: 20 - registry-url: 'https://registry.npmjs.org/' - - # Ensure npm 11.5.1 or later is installed - - run: npm install -g npm@latest - - run: npm publish --access public - ``` -### Limitations - -* Trusted publishing is supported only on GitHub-hosted runners. -* Self-hosted runners are not currently supported but are planned for future releases. - -### FAQ - -**Q: Do I need to set `NODE_AUTH_TOKEN` for Trusted Publisher (OIDC)?** - -No. OIDC replaces the need for tokens entirely. - -**Q: My package exists on npm, but `npm publish` fails with `E404 Not Found`. Why?** - -This usually indicates that the Trusted Publisher configuration does not exactly match the workflow run identity (repository, workflow filename, or environment), or that the workflow does not have permission to publish to the package or scope. - -All fields are case-sensitive and must match exactly. - - - -### Troubleshooting - -* Verify npm version: - ```sh - npm -v - -Ensure it is ≥ 11.5.1 -* Ensure `id-token: write` permission is set -* Check that the workflow filename matches exactly (including `.yml`) -* Ensure the repository and organization match `npm` configuration -* Ensure `repository.url` in `package.json` matches your GitHub repository ### References From 50201b87dbbcb74cae050cc73a19f7dcb81fb0fb Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Wed, 22 Apr 2026 11:41:59 +0530 Subject: [PATCH 5/7] Fix typo in Trusted Publisher (OIDC) documentation --- docs/advanced-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 7aa87c5e9..a76c22e61 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](https://docs.npmjs.com/trusted-publishers), which allow publishing packages from GitHub Actions using OpenID Connect (OIDC) instead of long-lived tokens. +Npm supports [Trusted Publishers](https://docs.npmjs.com/trusted-publishers), which allow publishing packages from GitHub Actions using OpenID Connect (OIDC) instead of long-lived tokens. Trusted publishing improves security by eliminating long-lived npm tokens and using short-lived OIDC credentials. This approach reduces the risk of credential leakage and simplifies authentication in CI/CD workflows. From ae1c5fa1ae26c9edce30dbaaa60e6d15f7ca6d69 Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Wed, 22 Apr 2026 13:41:04 +0530 Subject: [PATCH 6/7] Docs update for OIDC --- docs/advanced-usage.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index a76c22e61..e1a25c1fc 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -477,10 +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](https://docs.npmjs.com/trusted-publishers), which allow publishing packages from GitHub Actions using OpenID Connect (OIDC) instead of long-lived tokens. - -Trusted publishing improves security by eliminating long-lived npm tokens and using short-lived OIDC credentials. This approach reduces the risk of credential leakage and simplifies authentication in CI/CD workflows. - +Npm supports [Trusted Publishers](https://docs.npmjs.com/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 @@ -489,7 +486,7 @@ 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. +> 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). @@ -505,8 +502,8 @@ You must also configure a **Trusted Publisher** in npm for your package/scope th - uses: actions/setup-node@v6 with: - node-version: 24 - registry-url: 'https://registry.npmjs.org/' + node-version: '24' + registry-url: 'https://registry.npmjs.org' - run: npm ci - run: npm run build --if-present @@ -521,13 +518,13 @@ You must also configure a **Trusted Publisher** in npm for your package/scope th OIDC authentication is handled automatically via GitHub’s identity token. -> ⚠️ 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. +> 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. ### References -* https://docs.npmjs.com/trusted-publishers -* https://docs.github.com/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect +- [npm Trusted Publishers documentation](https://docs.npmjs.com/trusted-publishers) +- [GitHub Actions OpenID Connect (OIDC) overview](https://docs.github.com/en/actions/concepts/security/openid-connect) ## Use private mirror From e39eb663ad59fbe98597c6e9ef46a22cd831494e Mon Sep 17 00:00:00 2001 From: chiranjib-swain Date: Wed, 22 Apr 2026 16:35:29 +0530 Subject: [PATCH 7/7] Refine Trusted Publisher documentation for clarity and conciseness --- docs/advanced-usage.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index e1a25c1fc..4aa84c190 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](https://docs.npmjs.com/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 @@ -507,7 +507,7 @@ You must also configure a **Trusted Publisher** in npm for your package/scope th - run: npm ci - run: npm run build --if-present - - run: npm publish --access public + - run: npm publish ``` ### Important @@ -518,13 +518,9 @@ You must also configure a **Trusted Publisher** in npm for your package/scope th OIDC authentication is handled automatically via GitHub’s identity token. -> 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. +> **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. - -### References - -- [npm Trusted Publishers documentation](https://docs.npmjs.com/trusted-publishers) -- [GitHub Actions OpenID Connect (OIDC) overview](https://docs.github.com/en/actions/concepts/security/openid-connect) +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