Publish npm Packages from GitHub Actions Without NPM_TOKEN: Using Trusted Publishing with OIDC
Publishing an npm package through GitHub Actions traditionally requires a secret such as NPM_TOKEN. While this approach works, it also means storing a reusable publishing credential in your repository's automation configuration.
There is a better alternative: npm Trusted Publishing.
With Trusted Publishing, GitHub Actions authenticates to npm using OpenID Connect (OIDC). Instead of storing a long-lived npm publish token, GitHub identifies the workflow, and npm verifies whether that workflow is authorized to publish the package.
The practical benefit is reduced credential exposure. Your release workflow no longer needs a long-lived npm publishing secret.
This does not guarantee that your package or workflow is secure, but it removes one persistent credential from the release process.
How npm Trusted Publishing Works
The process relies on a trust relationship between npm and GitHub Actions.
You first register a trusted publisher in your npm package settings, specifying:
When the workflow runs, GitHub can issue an OIDC identity token to the publishing job. The npm CLI uses this identity to authenticate the publish request.
The authorization is specific to the configured repository and workflow. Another repository or workflow will not automatically receive publishing permission.
For GitHub Actions, npm currently requires:
A GitHub-hosted runner
Node.js 22.14.0 or later
npm CLI 11.5.1 or later
Make sure to check the actual npm version installed in your runner rather than assuming the version bundled with Node.js meets the requirement.
Step 1: Configure Trusted Publishing on npm
First, open npmjs.com and navigate to the settings page of the package you want to publish.
Find the Trusted Publisher section and select GitHub Actions.
Configure the following information:
| Field | Value |
|---|
| Provider | GitHub Actions |
| Owner | Your GitHub username or organization |
| Repository | Your repository name |
| Workflow filename | publish.yml |
| Environment | Your GitHub environment, if applicable |
A couple of details are important:
Workflow filename: Enter only the filename, such as publish.yml, not the full path .github/workflows/publish.yml.
Environment: If your GitHub Actions workflow uses a GitHub environment, configure exactly the same environment name in npm.
Also, make sure the repository.url field in your package.json exactly matches the GitHub repository.
For example:
{
"repository": {
"type": "git",
"url": "https://github.com/your-username/your-package.git"
}
}
One timing consideration: a newly created trusted publisher configuration must complete its first successful publish within two days, or the configuration expires. Therefore, configure it when you are ready to test your release workflow.
Step 2: Configure GitHub Actions
Next, create a workflow file:
.github/workflows/publish.yml
Here is an example that publishes your package whenever you push a version tag.
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'
package-manager-cache: false
- run: npm install --global 'npm@^11.5.1'
- run: npm ci
- run: npm test --if-present
- run: npm run build --if-present
- run: npm publish --access public
Replace the test and build commands with the scripts defined in your own package.json.
If you are publishing a public scoped package for the first time, --access public is required.
Understanding the Important Permissions
The most important part of this configuration is:
permissions:
contents: read
id-token: write
The id-token: write permission allows the publishing job to request an OIDC identity token from GitHub.
It does not grant permission to modify your repository contents.
Keep this permission limited to the publishing job rather than granting it globally to every job in your workflow.
Notice that the workflow does not contain either of these credentials:
NPM_TOKEN
NODE_AUTH_TOKEN
That is intentional.
When the trusted publisher is correctly configured and the required versions are installed, the npm CLI handles OIDC authentication automatically.
Step 3: Check npm's Allowed Actions Setting
There is one additional npm setting worth checking before running your release workflow.
Open your package's Trusted Publisher settings and review Allowed actions.
As of npm's current documentation, trusted publisher configurations created after September 3, 2026 default to allowing npm stage publish. If your workflow uses a direct npm publish command, make sure direct publishing is explicitly enabled.
Earlier configurations may have different defaults, so check the actual setting instead of assuming it.
What About Staged Publishing?
npm also supports staged publishing.
Instead of immediately making a package available, the workflow stages the release for review and approval by a maintainer before publication.
This can be useful for projects that require an additional approval step before releasing a new version.
If you choose staged publishing, follow npm's staged-publishing instructions and grant only the actions your workflow requires.
Step 4: Understand What Trusted Publishing Does Not Replace
Trusted Publishing removes the need for a long-lived npm publishing token, but it does not eliminate every authentication or security concern.
There are a few important limitations to understand.
1. Private Dependency Installation
OIDC Trusted Publishing authenticates the publishing process. It does not automatically authenticate dependency installation.
If npm ci needs access to private packages, you still need a separate read-only credential for installation.
Avoid reusing a publishing token for this purpose.
2. Workflow Security
A compromised workflow that is authorized to publish can still misuse its publishing permissions.
Protect your release process by:
Restricting who can create release tags.
Reviewing changes to GitHub Actions workflow files.
Using protected branches and release controls.
Requiring environment approval when appropriate.
Remember that OIDC establishes identity and authorization. It does not guarantee that the workflow itself is trustworthy.
3. Package Provenance
Trusted publishing through GitHub Actions automatically generates provenance for public packages built from public repositories.
However, provenance is not generated for a private source repository, even when the published npm package is public.
This is worth considering if package supply-chain transparency is important to your project.
Step 5: Test Your Release Workflow
Once everything is configured, push a version tag to trigger the publishing workflow.
For example:
git tag v1.0.0
git push origin v1.0.0
Then:
Open your repository's GitHub Actions page.
Find the triggered publishing workflow.
Check whether the publishing job completes successfully.
Verify that the new version appears on npm.
Confirm that the package's publishing settings show the expected trusted publisher.
After a successful release, review your npm publishing access settings and revoke any old automation tokens that are no longer needed.
Conclusion
npm Trusted Publishing provides a cleaner way to publish packages from GitHub Actions.
Instead of maintaining a long-lived NPM_TOKEN, you configure a trust relationship between your npm package and a specific GitHub Actions workflow.
The result is a release pipeline with fewer persistent secrets and a more narrowly defined publishing identity.
It is not a replacement for securing your GitHub repository or reviewing your release workflows, but it is a meaningful improvement to the way npm packages can be published.
For new npm package projects, Trusted Publishing is well worth considering.
References
❤️ Support This Blog
If this post helped you, you can support my writing with a small donation.
Thank you for reading.
Comments
Post a Comment