Solving the 'Not Found' Error: Seamless OIDC Publishing to npmjs with Yarn in GitHub Actions

Publishing packages to npmjs.com using GitHub Actions and OpenID Connect (OIDC) offers enhanced security and streamlined workflows. However, as Arad1el discovered in a recent GitHub Community discussion, integrating OIDC with Yarn can present some "teething issues," often manifesting as a cryptic "Not found" error during the publish step. This insight delves into the problem and provides a robust solution, ensuring your development activities remain smooth and secure.

The OIDC Publishing Challenge with Yarn in GitHub Actions

Arad1el was attempting to publish a security update to an existing npm package. Their setup involved GitHub Actions with OIDC Trusted Publisher configured on npmjs.com, targeting a specific repository and workflow file (npm-publish.yml). The workflow used Yarn for dependency installation and building, culminating in yarn publish --provenance. Despite careful configuration, the workflow failed with the error: error Couldn't publish package: "https://registry.npmjs.org/[package-name]: Not found".

This error is a common point of confusion. While it suggests the package doesn't exist, the reality, as explained by community experts like shivrajcodez and MHassan-Tariq, is that it's almost always an authentication failure. The npm registry returns a 404 when it cannot properly identify or authorize the publishing entity, rather than explicitly stating an authentication problem. This can be a significant roadblock in achieving your software project goals examples when timely updates are critical.

Unpacking the Root Cause: Yarn v1's OIDC Blind Spot

The core of the issue lies in the compatibility between Yarn v1 (Classic) and the modern OIDC/Provenance handshake required by npm's Trusted Publisher feature. Yarn v1's publish command is built on an older architecture that doesn't natively understand how to exchange a GitHub OIDC token for an npm session. When yarn publish --provenance is executed, it fails to provide the correct credentials, and the npm registry returns a 404 Not Found (effectively saying, "I don't know who you are, so I can't find a permission set for this package").

This is a crucial distinction for dev teams and delivery managers. Relying on an outdated mechanism for a critical security process introduces unnecessary friction and potential vulnerabilities. Understanding this root cause is the first step toward a more resilient CI/CD pipeline.

The Professional Fix: Bridging Yarn and OIDC with npm publish

The most stable and recommended way to leverage npm's Trusted Publishing while keeping your project's primary package manager as Yarn is to use Yarn for dependency management and building, but switch to the npm CLI for the actual publishing step. The npm CLI (v9.5.0+) is the official tool designed for OIDC/Provenance, natively handling the token exchange.

Here’s the updated workflow structure that resolved Arad1el's issue, incorporating best practices for secure and reliable package publishing:

name: Publish to npmjs
on: release:
  types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Required for OIDC
      contents: read
      # packages: write # Only needed if publishing to GitHub Packages; npm only needs id-token
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24 # Good choice, includes npm v11+
          registry-url: 'https://registry.npmjs.org/'
          # scope: '@your-scope' # Only if publishing a scoped package
          # always-auth: true # Generally not needed with OIDC, setup-node handles it
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Build package
        run: yarn build
      - name: Publish to npm via OIDC
        # We use npm here because it natively handles the OIDC token exchange
        run: npm publish --provenance --access public # --access public is crucial for unscoped public packages
        env:
          # NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # NOT REQUIRED with OIDC, leave this out! OIDC handles authentication directly.

Notice the critical change in the final step: npm publish --provenance --access public. This ensures that the OIDC token is correctly exchanged and the package is published with the necessary provenance information, enhancing the security and trustworthiness of your releases. The --access public flag is important for unscoped public packages, ensuring they are not accidentally published as private.

Critical Checklist for OIDC Trusted Publishing Success

Even with the correct npm publish command, OIDC is highly sensitive to configuration details. If you still encounter issues, meticulously review these "invisible" settings:

• Case Sensitivity: In your npmjs.com Trusted Publisher settings, the GitHub Organization/User and Repository names must match the casing in your GitHub URL exactly (e.g., Arad1el/my-repo vs. arad1el/my-repo).
• Workflow Filename: Ensure the workflow filename configured in npmjs.com (e.g., npm-publish.yml) matches the actual filename in your repository exactly. Even a capital letter or a missing .yml extension will cause the OIDC handshake to fail.
• package.json Repository Field: Ensure your package.json has a repository field that accurately points to the GitHub repository you are publishing from. This helps npm verify the source of the package.

  "repository": {
    "type": "git",
    "url": "https://github.com/arad1el/your-repo-name.git"
  }

• Scoped Packages: If your package is scoped (e.g., @my-org/my-package), ensure your package.json includes "publishConfig": { "access": "public" } if it's meant to be publicly accessible.
• Release Trigger: Your workflow runs on: release: types: [created]. Confirm you are creating a proper GitHub Release (not just pushing a tag). OIDC validation checks the workflow context carefully.

Why This Matters for Your Delivery Pipeline

For dev teams, product managers, and CTOs, overcoming these OIDC publishing hurdles is more than just a technical fix; it's about enhancing the security posture and efficiency of your entire delivery pipeline. Secure publishing mechanisms are fundamental to modern development activities. By embracing OIDC, you eliminate the need for long-lived, static authentication tokens, significantly reducing the risk of credential compromise.

A reliable and secure publishing workflow contributes directly to achieving your software project goals examples by:

• Improving Security: OIDC tokens are short-lived and tied to specific GitHub Actions runs, minimizing exposure.
• Streamlining Operations: No more manual token rotation or management, freeing up valuable developer time.
• Enhancing Trust: Provenance ensures consumers can verify the origin and integrity of your packages.
• Boosting Productivity: Fewer authentication errors mean less debugging and more focus on actual development.

This transition to OIDC, while it may have initial "teething issues," represents a significant leap forward in CI/CD security and automation. By understanding the nuances and applying the correct solutions, you can ensure your team's package publishing process is robust, secure, and contributes positively to your overall developer analytics and delivery metrics.

Conclusion

The "Not found" error when publishing to npmjs with Yarn and OIDC in GitHub Actions is a classic case of a misleading error message. The true culprit is Yarn v1's inability to natively handle the OIDC token exchange. The solution is straightforward: leverage the npm CLI for the final publishing step. By combining this fix with meticulous attention to OIDC configuration details, your team can unlock the full security and efficiency benefits of Trusted Publishing, ensuring your essential development activities remain secure and uninterrupted.