npm-publish-oidc.md

NPM publish using OIDC on github actions

➊ NPM Settings

➋ Github Action Settings

➌ .github/workflows/ci.yml

➍ Proper permissions are required.

permissions:
  contents: write
  id-token: write

Complete configuration

jobs:
  npm-publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          registry-url: 'https://registry.npmjs.org'

      # npm@v11.5.0+ is required for OIDC support
      # node@v22.0.0+ 
      # - name: Upgrade npm for OIDC support
      #   run: npm install -g npm@latest
      
      # node@v24.0.0+ 
      # https://github.com/orgs/community/discussions/176761
      # https://github.com/actions/setup-node/issues/1440#issuecomment-3571890875
      - run: NODE_AUTH_TOKEN="" npm publish --access public --provenance
        name: 📦 hotkeys-js to NPM
        continue-on-error: true

• https://github.com/orgs/community/discussions/176761
• actions/setup-node#1440 (comment)

A few tips!

• If you use node-version: 24, you don't even have to upgrade npm since it is already in the version covering OIDC
• --access public can be defined in package.json and is only required on first publish to know the access type of your package if you're using a scope (@)
• --provenance is by default when using OIDC
• You don't even need contents: write, only contents: read is enough!

Here's one I wrote for one of my packages

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: NODE_AUTH_TOKEN="" npm publish

A few tips!

• If you use node-version: 24, you don't even have to upgrade npm since it is already in the version covering OIDC
• --access public can be defined in package.json and is only required on first publish to know the access type of your package if you're using a scope (@)
• --provenance is by default when using OIDC
• You don't even need contents: write, only contents: read is enough!

Here's one I wrote for one of my packages

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: NODE_AUTH_TOKEN="" npm publish

@vexcited Great tips! However, contents: write is likely still required, since in most cases a tag needs to be created in the repository during publishing.

Yeah, it all depends on your CI; in my case I use a tool that creates a tag in the repository and the tag triggers the publish CI so I don't need the write permission. I was just giving the tip in case people think write is required

@jaywcjlove Something prob important for this guide that I found in trial error after a LOT of version git reverts.

The GitHub org name is case sensitive. My project is LumeWeb. I CANNOT use lumeweb in the repo config. I also had to set the repo url in all my package.json files...

Based on https://search.sigstore.dev/?logIndex=820957132, it seems everything gets hashed which would explain why the case sensitivity matters, but IMO this isn't well communicated and the DX def needs to improve 😅 . So hopefully me posting here help someone else as I just wasted nearly 4 hours on this issue...

@jaywcjlove Something prob important for this guide that I found in trial error after a LOT of version git reverts.

The GitHub org name is case sensitive. My project is LumeWeb. I CANNOT use lumeweb in the repo config. I also had to set the repo url in all my package.json files...

Based on https://search.sigstore.dev/?logIndex=820957132, it seems everything gets hashed which would explain why the case sensitivity matters, but IMO this isn't well communicated and the DX def needs to improve 😅 . So hopefully me posting here help someone else as I just wasted nearly 4 hours on this issue...

@pcfreak30 Are you referring to the need to keep the repository name in npm consistent with the GitHub repository name? And also setting the repository in the project's package.json to match the name in both GitHub and npm configurations?

@jaywcjlove Something prob important for this guide that I found in trial error after a LOT of version git reverts.
The GitHub org name is case sensitive. My project is LumeWeb. I CANNOT use lumeweb in the repo config. I also had to set the repo url in all my package.json files...
Based on https://search.sigstore.dev/?logIndex=820957132, it seems everything gets hashed which would explain why the case sensitivity matters, but IMO this isn't well communicated and the DX def needs to improve 😅 . So hopefully me posting here help someone else as I just wasted nearly 4 hours on this issue...

@pcfreak30 Are you referring to the need to keep the repository name in npm consistent with the GitHub repository name? And also setting the repository in the project's package.json to match the name in both GitHub and npm configurations?

Yes. Basically casing matters. I verified unintentionally by missing a package I forgot to update and it failed until i fixed the org name on the /access settings page in npmjs.com

Thanks for the guide. It finally helped me fix my OIDC issue 🎉
This should really be in npm’s troubleshooting section.

The NODE_AUTH_TOKEN="" did the trick for me!