Skip to search Skip to content
Table of contents
Trusted publishing allows you to publish npm packages directly from your CI/CD workflows using OpenID Connect (OIDC) authentication, eliminating the need for long-lived npm tokens. This feature implements the trusted publishers industry standard specified by the Open Source Security Foundation (OpenSSF), joining a growing ecosystem including PyPI, RubyGems, and other major package registries in offering this security enhancement.
Note: Trusted publishing requires npm CLI version 11.5.1 or later.
Trusted publishing creates a trust relationship between npm and your CI/CD provider using OIDC. When you configure a trusted publisher for your package, npm will accept publishes from the specific workflow you’ve authorized, in addition to traditional authentication methods like npm tokens and manual publishes. The npm CLI automatically detects OIDC environments and uses them for authentication before falling back to traditional tokens.
This approach eliminates the security risks associated with long-lived write tokens, which can be compromised, accidentally exposed in logs, or require manual rotation. Instead, each publish uses short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused.
Trusted publishing currently supports:
Self-hosted runners are not currently supported but are planned for future releases.
Navigate to your package settings on 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.
Configure the following fields:
publish.yml)
.yml or .yaml extension.github/workflows/ in your repository
Configure the following fields:
.gitlab-ci.yml)
.yml extension
Note: Each package can only have one trusted publisher configured at a time.
Add the required OIDC permissions to your workflow. Here’s a complete example:
name: Publish Package
on:
push:
tags:
- 'v*'
permissions:
id-token: write # Required for OIDC
contents: read
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
# Ensure npm 11.5.1 or later is installed
- name: Update npm
run: npm install -g npm@latest
- run: npm ci
- run: npm run build --if-present
- run: npm test
- run: npm publish
The critical requirement is the id-token: write permission, which allows GitHub Actions to generate OIDC tokens. Learn more in GitHub’s OIDC documentation.
Configure the OIDC ID token in your pipeline:
stages:
- test
- build
- publish
variables:
NODE_VERSION: '20'
test:
stage: test
image: node:${NODE_VERSION}
script:
- npm ci
- npm test
publish:
stage: publish
image: node:${NODE_VERSION}
id_tokens:
NPM_ID_TOKEN:
aud: "npm:registry.npmjs.org"
script:
# Ensure npm 11.5.1 or later is installed
- npm install -g npm@latest
- npm ci
- npm run build --if-present
- npm publish
only:
- tags
The id_tokens configuration tells GitLab to generate an OIDC token for npm. Learn more in GitLab’s OIDC documentation.
You can modify or remove your trusted publisher configuration at any time through your package settings on npmjs.com. 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.
Once you’ve configured trusted publishers for your package, we strongly recommend restricting traditional token-based publishing access for enhanced security.
Trusted publishers use short-lived, scoped credentials that are generated on-demand during your CI/CD workflow, eliminating the need for long-lived tokens. By restricting traditional token access while using trusted publishers, you reduce potential security risks associated with credential management.
Note: The “disallow tokens” setting only affects traditional token authentication. Your trusted publishers will continue to work normally, as they use OIDC tokens.
If you’re transitioning from token-based publishing:
This ensures a smooth transition without disrupting your release process.
When you publish using trusted publishing, npm automatically generates and publishes provenance attestations for your package. This happens by default—you don’t need to add the --provenance flag to your publish command.
Provenance provides cryptographic proof of where and how your package was built, allowing users to verify its authenticity. This automatic generation only applies when all of these conditions are met:
Note: Provenance generation is not supported for private repositories, even when publishing public packages.
While we strongly recommend keeping provenance enabled, you can disable it if needed. Set the provenance option to false in any of these ways:
Using environment variable:
NPM_CONFIG_PROVENANCE=false npm publish
In your .npmrc file:
provenance=false
In your package.json:
{
"publishConfig": {
"provenance": false
}
}
When trusted publishing is available for your workflow, always prefer it over long-lived tokens. Traditional npm tokens pose several security risks:
Trusted publishing eliminates these risks by using short-lived, workflow-specific credentials that are automatically managed and cannot be extracted.
While trusted publishing handles the publish operation, you may still need authentication for installing private npm dependencies. For this scenario, we recommend:
# GitHub Actions example
- uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
# Ensure npm 11.5.1 or later for trusted publishing
- run: npm install -g npm@latest
# Use a read-only token for installing dependencies
- run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_READ_TOKEN }}
# Publish uses OIDC - no token needed
- run: npm publish
Always use read-only granular access tokens for installing dependencies. This limits potential damage if the token is ever compromised.
Consider implementing these additional security practices:
If you encounter an “Unable to authenticate” error when publishing, first verify that the workflow filename matches exactly what you configured on npmjs.com, including the .yml extension. The filename is 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.
Note: npm does not verify your trusted publisher configuration when you save it. Double-check that your repository, workflow filename, and other details are correct, as errors will only appear when you attempt to publish.
If your package has private dependencies and npm install or npm ci is failing with authentication errors, remember that trusted publishing only applies to the npm publish command. You’ll still need to provide a read-only token for installing private packages as shown in the examples above.
For packages in private repositories, provenance will not be generated even though you’re using trusted publishing. This is a known limitation that applies regardless of whether your package itself is public or private.
Some GitHub Actions workflows use workflow_call to invoke other workflows that run npm publish, or use workflow_dispatch for manual publishing. When this happens, validation checks the calling workflow’s name instead of the workflow that actually contains the publish command, which can cause configuration mismatches.
Trusted publishing currently supports only cloud-hosted runners. Support for self-hosted runners is intended for a future release. Each package can only have one trusted publisher configured at a time, though you can update this configuration as needed.
OIDC authentication is currently limited to the publish operation. Other npm commands such as install, view, or access still require traditional authentication methods. The npm whoami command will not reflect OIDC authentication status since the authentication occurs only during the publish operation.
We intend to expand trusted publishing support to additional CI/CD providers and enhance the feature based on community feedback.
4contributors 
reggi 
leobalter 
jrvidal 
generalmimon
Last edited by reggi on September 22, 2025