CI/CD, Publishing & npm Provenance

This section covers the release engineering side of dual-format npm packages: automating builds and publishes with GitHub Actions, generating cryptographic Sigstore provenance for every tarball, replacing long-lived tokens with OIDC trusted publishing, and validating a package’s shape before it ever reaches the registry. It is written for maintainers and platform engineers who need a release pipeline that is reproducible, auditable, and resistant to supply-chain tampering.

Quick-Reference: Key Terms

Core Concepts

The automated release pipeline

A dual-format package cannot be published safely by running npm publish from a developer’s laptop. The build step must run in a clean, reproducible environment so the ESM and CJS artifacts in the tarball match exactly what CI validated — a laptop with stale dist/ output or an uncommitted local patch produces a tarball nobody can audit. The baseline pipeline triggers on a version tag, installs with a locked lockfile, builds both formats, validates the result, and only then publishes:

name: Release
on:
  push:
    tags:
      - 'v*'

permissions:
  contents: read
  id-token: write   # required for --provenance and OIDC trusted publishing

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npx publint --strict
      - run: npx attw --pack .
      - run: npm publish --provenance --access public

Every step is ordered deliberately: npm ci (not npm install) enforces the committed lockfile, the build runs before validation so publint inspects real output, and npm publish is the last step so a validation failure never reaches the registry.

How provenance attestation works

npm publish --provenance asks npm to generate a Sigstore attestation during the publish step instead of, or in addition to, signing with a maintainer’s personal key. The CI job proves its identity to Sigstore’s Fulcio certificate authority using the workflow’s short-lived OIDC token — no long-lived signing key is stored anywhere. Fulcio issues a certificate valid for minutes, npm’s CLI signs the package manifest and tarball digest with it, and the resulting attestation is written to Sigstore’s Rekor transparency log, a public, append-only ledger.

# Inside the CI job, after the build:
npm publish --provenance --access public

# npm CLI (>= 9.5) performs, transparently:
# 1. Requests a short-lived OIDC token from the CI provider (GitHub Actions)
# 2. Exchanges it for a Fulcio-issued signing certificate
# 3. Signs the tarball digest + build metadata
# 4. Uploads the attestation to Rekor and links it to the published version

The result is a verifiable answer to “which commit and which workflow run produced this exact tarball” — without requiring consumers to trust the maintainer’s personal machine or a shared secret.

Token auth vs OIDC trusted publishing

Classic npm automation relies on a long-lived NPM_TOKEN stored as a repository secret. It works, but the token grants publish rights indefinitely until manually rotated or revoked, and a leaked token compromises every package it can publish. OIDC trusted publishing removes the stored secret entirely: the maintainer configures npmjs.com to trust a specific GitHub repository and workflow file, and at publish time npm exchanges the workflow’s ephemeral OIDC token for a publish credential that expires within minutes.

# No NPM_TOKEN secret required at all — trust is configured on npmjs.com
permissions:
  id-token: write
  contents: read

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 20
      registry-url: 'https://registry.npmjs.org'
  - run: npm ci && npm run build
  - run: npm publish --provenance

If the workflow file, branch, or repository does not exactly match what was registered as a trusted publisher, the exchange fails closed — there is no fallback to a stored token unless one is explicitly configured as a backup.

Hazard and Failure-Mode Inventory

HAZARD PREVENTION

Symptom: npm ERR! code ENEEDAUTH during npm publish in CI, even though a token secret is configured.

Root cause: The NPM_TOKEN environment variable was not exported to the npm publish step, the token expired, or registry-url was omitted from actions/setup-node, leaving .npmrc unconfigured.

Fix: Pass registry-url: 'https://registry.npmjs.org' to setup-node, export NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} on the publish step, or switch to OIDC trusted publishing to remove the token dependency entirely.

HAZARD PREVENTION

Symptom: npm publish --provenance fails with an error mentioning the OIDC token could not be obtained, or provenance silently does not appear on the published version.

Root cause: The workflow’s permissions block does not grant id-token: write. Without it, the runner never issues the short-lived OIDC token that Sigstore’s Fulcio authority needs to sign the attestation.

Fix: Add permissions: { id-token: write, contents: read } at the job or workflow level in your release workflow.

HAZARD PREVENTION

Symptom: npm publish --provenance succeeds for a public package but fails, or is rejected on the registry, for a scoped package that has never been published before.

Root cause: Scoped packages (@scope/name) default to private on first publish. Provenance attestations are only supported for packages published with public visibility; omitting --access public on a scoped package’s first publish causes a registry-side rejection unrelated to the attestation itself.

Fix: Always pass --access public alongside --provenance the first time a scoped package is published, as shown in publishing with npm provenance in GitHub Actions.

HAZARD PREVENTION

Symptom: A published version is missing files a consumer expects, or ships a stale dist/ build from a previous run — even though the workflow appears green.

Root cause: The build step was skipped or cached incorrectly, and npm publish ran against a leftover dist/ directory from an earlier job, a local checkout, or a partially restored cache.

Fix: Run the build step unconditionally before publish in the same job (never a separate, independently-cacheable job), and add a pre-publish validation step that fails the pipeline if publint finds paths that do not resolve.

Decision Guide: Token, OIDC, or Both?

Which authentication method you use to publish depends on two questions: can your CI provider present an OIDC identity token, and can you pin a single trusted workflow and branch on npmjs.com? The tree below maps those answers to the three outcomes.

• OIDC trusted publishing is the default when your CI can present an OIDC token and you can register a fixed workflow file and branch as a trusted publisher on npmjs.com — no long-lived secret is stored anywhere.
• A scoped automation token is the fallback when workflows are dynamic (matrix publishes or generated workflow files) so a single trusted-publisher record cannot cover them. Use a Granular Access Token scoped to the one package.
• A Granular Access Token is the only option for self-hosted runners or CI providers that cannot issue OIDC tokens; rotate it on a schedule.

Topic Index

Frequently Asked Questions

Related

• Module System Fundamentals & Dual-Package Resolution — the exports field and dual-format output this pipeline builds and validates before every publish.
• Tree-Shaking & Bundle Optimization — bundle-size regressions are worth catching in the same CI run that validates and publishes a release.
• TypeScript Configuration & Build Tooling — the tsconfig.json and build-tool settings that produce the declaration files attw checks in this pipeline.
• Mastering the package.json Exports Field — the condition map that publint and attw both validate against during pre-publish checks.

← Back to home