publish-npm-package

Publish npm Package

Set up npmjs publishing via GitHub Actions with a complete, internally consistent release flow: auth, version management, package-manager installs, workflow trigger, provenance, validation, and recovery. Decisions and routing live here; full YAML and tool deep-dives live in references/.

When to use

Use this skill if the request is one of:

• "publish this package to npm", "set up npm publishing", "automate npm releases"
• "npm publish from GitHub Actions", "release workflow for npm", "npm CI/CD"
• "trusted publishing", "OIDC for npm", "NPM_TOKEN provenance", "id-token: write"
• "semantic-release", "changesets", "release-please", "automate version bumps"
• "first publish of a new package", "bootstrap npm package", "link GitHub repo to npm"
• "why is my npm publish failing", "EOTP / ENEEDAUTH / E403 in CI", "npm whoami in Actions"

package.json / repo signals that should pull this skill in:

• "name" field plus "version" and a repository.url pointing at GitHub
• .github/workflows/*.yml with npm publish, setup-node, id-token: write, or NPM_TOKEN
• .npmrc with //registry.npmjs.org/:_authToken or ${NODE_AUTH_TOKEN}
• presence of .releaserc*, release.config.js, .changeset/, or .release-please-*.json
• scoped name (@scope/name) plus publishConfig.access decisions

Do NOT use this skill when:

• deploying apps/services to a runtime (Railway, Vercel, Fly) — use the platform skill (e.g. run-railway)
• writing the package's own runtime code, SDK internals, or APIs — use the relevant build-* skill
• publishing to a non-npm registry (Docker Hub, GHCR, PyPI, crates.io) and npm is not also in scope
• the only ask is which npm / package-manager command to run with no CI or release-automation context

Decide auth first, versioning second, then route to the workflow template

Always follow this order. Skipping it produces half-configured release automation.

1. Classify the repo (table below).
2. Pick auth: OIDC trusted publishing, or token (NPM_TOKEN → NODE_AUTH_TOKEN).
3. Pick versioning: semantic-release, changesets, release-please, or manual.
4. Route to the exact workflow template in references/workflows/.
5. Check package/repo prerequisites and lockfile/package-manager.
6. Verify with npm pack --dry-run, build/test in CI, tool-specific dry runs.
7. If the repo is mid-migration or already failing, jump to recovery routing at the bottom.

Classify the repo first

Answer these and record the answers — they drive every later decision:

1. Public or private package?
2. GitHub Actions on a GitHub-hosted runner (vs self-hosted / GHES / non-GitHub CI)?
3. Single package or monorepo / workspaces?
4. Conventional commits actually used (majority of meaningful commits in type: description form)?
5. Auto-publish on every releasable merge, or human-reviewed Release/Version PR?
6. Greenfield (never published) or already published with tags/versions?
7. Target really npmjs.org?

Derive answers from package.json + workspace manifests → existing workflows → git remote/tags → npm registry state. If still ambiguous, stop and ask — do not guess.

Decision matrix

Auth lanes — keep them separate

Auth rules:

• Default to OIDC whenever supported. Trusted publishing means zero npm secrets — if the publish step has NODE_AUTH_TOKEN or NPM_TOKEN, it is token auth, not trusted publishing, even if id-token: write is set.
• OIDC requires the package to already exist on npm. First publish of a brand-new package always bootstraps with a granular token, then switches to OIDC after linking the repo on npm.
• OIDC does not work on self-hosted runners. Use a granular token there.
• Use secrets.NPM_TOKEN exposed as NODE_AUTH_TOKEN. Do not run npm login in CI. Avoid classic automation tokens for new work.
• One granular token per repo or workflow surface; rotate on a schedule.

Read the full lane:

• references/auth/oidc-trusted-publishing.md — OIDC bootstrap, repo linking, provenance defaults
• references/auth/granular-tokens.md — granular token creation, scoping, rotation, secret wiring

Local publish vs CI publish — know which mode you're in

Mixing these up is the #1 cause of EOTP / ENEEDAUTH errors.

Guardrail: NODE_AUTH_TOKEN as a bare env var only works when an .npmrc contains ${NODE_AUTH_TOKEN}. In GitHub Actions, actions/setup-node writes that file when registry-url is set. On a developer machine, npm ignores NODE_AUTH_TOKEN unless the placeholder .npmrc exists.

Local publish (developer terminal)

Check existing auth before issuing tokens:

npm whoami --registry https://registry.npmjs.org
echo "${NPM_TOKEN:+NPM_TOKEN is set}"
cat

Wire the token (pick one):

Guardrail: --//registry.npmjs.org/:_authToken=TOKEN is not a security risk on a local terminal. The "wrong" label in references/auth/granular-tokens.md applies only to CI logs.

CI publish (GitHub Actions)

Pure trusted publishing — no npm secret:

Token auth — NODE_AUTH_TOKEN env on the publish step plus setup-node registry-url:

Diagnose "EOTP when token should bypass 2FA"

If a granular automation token with "Bypass 2FA" still gets EOTP:

1. npm is not using your token — it has fallen back to interactive session auth.
2. Run npm whoami. A personal username confirms session auth is active.
3. Fix the wiring (CLI flag locally, setup-node + NODE_AUTH_TOKEN in CI). Do not rotate the token.

npm whoami does not validate trusted publishing. OIDC auth applies only during npm publish itself.

Versioning models — pick the model, not the tool

Versioning rules:

• Monorepo default: changesets. Use release-please only when conventional commits already drive the repo.
• changesets is not monorepo-only. Single-package repos without conventional commits that want a human-reviewed Version PR are a valid use case.
• Distinguish greenfield ("team will adopt conventional commits going forward") from existing repo ("commits already lack them"). Existing repos with inconsistent history → changesets, not semantic-release.
• For existing published packages, bootstrap baseline state before the first automated run (initial tag for semantic-release; aligned config + manifest for release-please; initialized config for changesets).

Guardrail: "Current version" in the release-please manifest = the version in package.json. For greenfield never-published packages, set it to whatever package.json says (typically 1.0.0 or 0.1.0). Do not guess 0.0.0.

Workflow templates — do not hand-assemble YAML from memory

Monorepos: read references/monorepo-publishing.md before choosing a workspace flow. Prefer the changesets template; fall back to release-please when conventional commits already exist; do not default to semantic-release for monorepos.

Guardrail: The workflow templates are the source of truth for full GitHub Actions YAML. The versioning references explain tool config, customization, and tool-specific failure modes — they are not standalone YAML sources.

Pre-implementation prerequisites

Package + repo

• Code pushed to a GitHub repository.
• package.json.repository.url exactly matches the GitHub repo URL, including casing.
• Scoped public packages set publishConfig.access: "public" (or equivalent).
• For pure trusted publishing, do not set publishConfig.provenance; npm auto-generates provenance for eligible public packages. Provenance config belongs to the token+provenance lane only.
• Lockfile committed; CI uses the matching deterministic install.
• npm pack --dry-run matches the intended tarball. If it includes src/ while main/module/types/exports point at dist/, stop and fix packaging before touching CI.
• Packaging shape (files, exports, types, dual ESM/CJS): references/package-config.md.

Lockfile and package-manager detection

Multiple lockfiles: stop and reconcile the package-manager choice before changing release automation.

CI

• actions/setup-node with registry-url: https://registry.npmjs.org.
• Build/test runs in the same job (or upstream of) publish.
• concurrency set to avoid publish races.
• Permissions least-privilege and explicit.
• Templates use actions/setup-node@v6, Node 24, package-manager-cache: false unless the repo deliberately keeps tag-readable examples.
• For production: pin actions to full SHAs with tag comments — see references/supply-chain.md.

First-publish bootstrap (greenfield → OIDC)

Guardrail: Trusted publishing requires the package to already exist on npm. Brand-new packages must bootstrap with token auth before linking trusted publishing.

1. Create a granular access token on npmjs.com (references/auth/granular-tokens.md).
2. Add it as NPM_TOKEN in GitHub Actions secrets.
3. Publish once: npm publish --access public, or use a token-based workflow template for the first release.
4. On https://www.npmjs.com/package/<your-package>/access → Publishing access → Add GitHub Actions to link the repo.
5. Remove NPM_TOKEN and switch the workflow to pure OIDC.

Migration prerequisites

• semantic-release: full git history (fetch-depth: 0) and a baseline tag.
• release-please: config + manifest aligned to the current package.json version.
• changesets: contributor rule for adding changesets and clear handling of empty changesets.

Guardrails — half-configured release automation is worse than none

• Prefer OIDC over granular tokens; granular tokens over classic automation tokens.
• Prefer changesets over semantic-release for monorepos unless there is a strong existing reason not to.
• Prefer release-please over semantic-release when the team wants a human-reviewed Release PR.
• Prefer workflow templates from the references over inventing YAML from memory.
• Do not pick semantic-release without real conventional commits, fetch-depth: 0, and a current toolchain that supports the chosen auth.
• release-please needs the two-job pattern: one job creates/updates the Release PR, a second publish job runs only when release_created == 'true'.
• Do not assume OIDC works on self-hosted runners.
• Do not commit tokenized .npmrc files. Placeholder-based .npmrc is fine; real tokens are not.
• Do not forget scoped public package access; E403 on a scoped package usually means publishConfig.access: "public" was never configured.
• Do not add --provenance to pure trusted-publishing baselines. Use it only for token+provenance lanes.
• Do not use pull_request_target to expose release secrets to untrusted code.
• If the repo is mid-migration, finish auth + versioning + workflow + bootstrap together. Do not ship a half-state.

Validation scripts

Bundled helpers — read the paired .md for flags; do not load script source during normal use.

Verification before declaring done

Always run:

• scripts/check-package-json.mjs [package-dir] (or equivalent in the target repo)
• scripts/dry-run-publish.sh [package-dir] or npm pack --dry-run
• build + test in the same workflow that publishes
• a check that the chosen versioning tool is wired, not just installed

Auth-specific:

Tool-specific:

Guardrail: release-please has no built-in dry-run equivalent. Verify config + manifest files and manifest/package.json alignment.

Output contract

When setup or diagnosis is complete, report:

• selected auth lane and versioning model
• files changed
• exact publish workflow trigger
• package name, version, npm dist-tag
• npm package URL (https://www.npmjs.com/package/<name>)
• GitHub release / tag URL when the flow creates one
• validation commands actually run
• provenance / signature verification status
• rollback or recovery note for failed or wrong publishes

Recovery routing

If the task is about an existing failure, jump straight to the narrowest reference.

Smallest reading set by scenario

• Public single package, fully automatic: references/auth/oidc-trusted-publishing.md + references/versioning/semantic-release.md + references/workflows/oidc-workflows.md (#1) + references/supply-chain.md.
• Public single package, reviewable gate: references/auth/oidc-trusted-publishing.md + references/versioning/release-please.md or references/versioning/changesets.md + references/workflows/oidc-workflows.md (#3 or #2) + references/supply-chain.md.
• Monorepo / workspaces: references/monorepo-publishing.md + references/versioning/changesets.md (default) or references/versioning/release-please.md + matching OIDC/token workflow section + references/supply-chain.md.
• Private package, self-hosted runner, or non-GitHub CI: references/auth/granular-tokens.md + chosen versioning reference + matching section in references/workflows/token-workflows.md.
• Failing existing workflow: references/common-issues.md + auth reference for the current mode + versioning reference for the current tool.

Known traps — quick reference

Final reminder

Keep SKILL.md focused on decisions, sequencing, and guardrails. Read only:

1. the auth reference,
2. the versioning reference,
3. the exact workflow-template section,
4. and references/common-issues.md / references/supply-chain.md only when needed.

Do not expand into full YAML or packaging deep dives here when the references already cover them.*