node-release

---
name: node-release
description: Cuts and automates npm releases - Changesets, semantic-release or release-please, npm trusted publishing (OIDC) with provenance, the first-publish bootstrap, staged publishing, changelogs and tags. Use when the user asks to release, version, publish to npm, or remove tokens from publish workflows. Not for package exports/bundling artifacts or verifying dependency provenance.
license: MIT
---

# node-release

Automates versioning and npm publishing with **no long-lived secrets and no
guessed facts**. The failures this skill fixes: models wire `NPM_TOKEN` secrets
in 2026, miss that a package's *first* version can't be published via OIDC, get
the trusted-publisher registration subtly wrong (case, filename, indirection),
and leave releases half-done when publish fails after tagging.

## When NOT to use

- Exports maps, bundling, tarball contents → `node-packaging` (release assumes
  its gates already pass).
- Verifying *dependencies'* provenance → `node-supply-chain`.
- Test/lint CI → `node-ci`.

## Workflow

1. **Pick the release tool** by workflow reality (decision table in
   `references/release-playbook.md`): Changesets (human-written notes,
   monorepos), semantic-release (strict conventional commits, fully
   autonomous), release-please (PR-gated review of each release).
2. **Trusted publishing (OIDC) — the default auth**; all requirements are
   version-gated in the playbook with the official npm doc links (CLI/Node
   minimums on the runner, GitHub-hosted runners, exact repo + workflow-filename
   registration match, `workflow_call` indirection caveat). Provenance is
   attached automatically under trusted publishing.
3. **Bootstrap gotcha — say it before it bites**: a brand-new package cannot be
   first-published via OIDC; the playbook's bootstrap procedure covers the one
   manual publish, then registration, then token revocation and account-level
   trusted-publishing-only enforcement.
4. **Write the publish workflow** from the playbook's YAML: minimal permissions
   (`id-token: write`, `contents: read/write` only as needed), SHA-pinned
   third-party actions (consistent with `node-supply-chain` policy), publish
   gated on the `node-packaging` checks.
5. **Failure-ordering discipline**: publish before tagging (or make retries
   idempotent); never delete published tags — releases are immutable.
6. **Verify end-to-end**: dry-run, then a real publish of a prerelease/dist-tag
   where possible; confirm provenance on the registry page; only then revoke
   legacy tokens.

## Output spec

A working automated release pipeline: version + changelog + tag + npm publish
with provenance, zero long-lived registry secrets after cutover, bootstrap and
rollback procedures documented in the repo, staged/prerelease channel decided
deliberately.

## Gotchas

- Trusted-publisher registration is exact-match: owner/repo casing and workflow
  filename including extension; publishing from a reusable (`workflow_call`)
  workflow validates against the *calling* file.
- OIDC does not make a compromised workflow safe — it removes stored-secret
  theft; workflow-file review still matters (CODEOWNERS on `.github/`).
- Tag-then-fail leaves consumers seeing a version npm doesn't have — ordering
  or idempotency, pick one explicitly.
- All npm-side specifics (minimums, staged publishing, token lifetimes) drift:
  the playbook version-gates each with its primary source — re-verify on setup.

## Files

- `references/release-playbook.md` — tool decision table, OIDC setup with
  version-gated requirements + doc links, bootstrap procedure, publish workflow
  YAML, failure-ordering patterns, dist-tag/prerelease guidance.