Maintainer guide for publishing a new version of the @pharn-dev/pharn npm package.
Releases publish on merge: a pull request that bumps the version is the
release. When it merges to main,
.github/workflows/publish.yml publishes to
npm, then tags the commit and creates the GitHub Release. Authentication is
npm Trusted Publishing (OIDC) — there are no npm tokens anywhere in this
repository or in its GitHub Actions secrets.
The canonical npm package is @pharn-dev/pharn (org-scoped) —
https://www.npmjs.com/package/@pharn-dev/pharn. It exposes a single pharn bin.
The unscoped name
pharnis not publishable: npm rejects it with E403 as too similar to existing packages (yarn,charm,sharp), and a scoped name sidesteps that similarity check — so@pharn-dev/pharnis canonical. An earlier@pharn-dev/pharn@0.2.0was published then unpublished on 2026-07-22, so0.2.0is permanently burned on this name; releases resumed at0.3.0. The installed binary stayspharn.
publish.yml uses npm Trusted Publishing (OIDC): at publish time the
workflow exchanges a short-lived GitHub OIDC id-token with npm — no long-lived
credential is stored or passed.
- No secrets, no tokens — not in the repo, not in Actions secrets, not in
the workflow.
permissions: id-token: writeis what enables the OIDC exchange (and the--provenanceattestation); it is not a secret. - The Trusted Publisher is configured on npmjs.com for package
@pharn-dev/pharn, pinned to workflowpublish.ymland the GitHub deployment environmentnpm-publish. - If a publish ever fails asking for a token, the Trusted Publisher config is broken — fix it on npmjs.com. Never add an npm token secret.
Put the release in the pull request that ships the change (or in a PR of its own, when several merged changes go out together):
-
Bump the version in
package.jsonandpackage-lock.json(SemVer, plainX.Y.Z— prereleases are refused):npm version --no-git-tag-version 0.12.0
-
Update
CHANGELOG.md. Move the[Unreleased]entries under a new## [X.Y.Z] — YYYY-MM-DDheading, and refresh the compare links at the bottom ([Unreleased]now compares fromvX.Y.Z; add a[X.Y.Z]line). Every link must name a tag that exists:tests/release-consistency.test.tschecks them against itsKNOWN_TAGSlist (the CI checkout fetches no tags), allowingvX.Y.Zitself beforepublish.ymlcreates it. So the bump after this one addsvX.Y.ZtoKNOWN_TAGS—git ls-remote --tags originshows what exists. The section under that heading becomes the GitHub Release notes, verbatim. -
Merge the PR once the required checks pass. The
Testcheck includestests/release-consistency.test.ts, which fails the PR whenpackage-lock.jsondoes not carry the same version orCHANGELOG.mdhas no non-empty section for it — so a half-done bump is caught before the merge.
A PR that does not bump the version releases nothing: leave the version
alone and add your entry under [Unreleased]. Dependabot and docs merges work
the same way. Whether a PR should bump, and to which level, is the author's and
the reviewer's call; no check can know that.
Every push to main runs publish.yml. Its four jobs run one after another,
and a workflow-level concurrency group keeps two runs from overlapping:
gaterefuses any ref other thanmain, requirespackage.jsonversionto be plainX.Y.Z, and asks the remote whether the tagvX.Y.Zexists (git ls-remote --exit-code). Tag present → the run ends here, green, having published nothing. Tag absent → release. Any other answer (network, auth) fails the run rather than guessing.buildholds no publish rights (id-tokenis not granted to it). Before installing anything it checks the version again, that the commit is contained inmain, and extracts the release notes withscripts/release-notes.mjs(a missing or empty CHANGELOG section fails here). It then runsnpm ci,npm run checkandnpm run test:coverage, packs the tarball (npm pack, whoseprepackbuilds it), installs that tarball into a scratch directory and runspharn --version, and uploads the tarball and the notes as an artifact.publishis the only job withid-token: writeand thenpm-publishenvironment. It checks out nothing and installs nothing: on node 24, whose bundled npm already satisfies the npm >= 11.5.1 Trusted Publishing needs (an Assert npm floor step enforces that), it asks the registry whether the version is already published — HTTP 200 skips the publish, 404 publishes, anything else fails the run — and then runsnpm publish <tarball> --provenance --access public --ignore-scripts. The--provenanceflag overridespublishConfig.provenance: false, so the release carries a signed provenance attestation.releaseis the only job withcontents: write. It checks out nothing and installs nothing: it runsgh release create vX.Y.Zat the built commit with the extracted notes, which also creates the tag. A Release that already exists is left alone.
npm comes first and the tag second, so a tag always means the version is on
npm. A Release created with the workflow's GITHUB_TOKEN starts no other
workflow, which is why tagging happens inside this run.
Why the split: every step of a job that holds id-token: write can request the
token npm trades for publish rights. Keeping the dev toolchain (install scripts,
linters, tests, bundler) out of that job means a compromised dev dependency can
no longer publish on its own. It can still influence the tarball's content in
build — the residual this does not close.
Note that pharnVersion (this package) and skillsVersion (upstream's
SKILLS_VERSION, which an install records separately) are independent numbers.
Releasing the CLI neither reads nor moves the content version. If a release
requires newer content, coordinate upstream's MIN_CLI file in the same window
— that is the handshake that refuses an under-versioned CLI.
- Re-run it. Every job is safe to repeat: the gate releases only while the
tag is absent,
publishskips a version npm already has, andreleaseleaves an existing Release alone. A run that failed after npm but before the tag picks up where it stopped. - A failed run that nobody re-runs is picked up by the next merge. Its
gatestill finds no tag for the version onmain, so it releases that version — built from the later commit, which includes whatever merged in between (a docs or dependency change, say). Re-run the failed run first if the release should contain exactly the bump commit. - A run that was cancelled or never ran (see the queueing note below) can be
started again from Actions → publish → Run workflow on
main. It releases the version currently onmain, if that version has no tag yet. - A tag that exists without a release behind it (pushed by hand, say) makes
the gate skip that version for good. Delete it
(
git push --delete origin vX.Y.Z) and re-run, or bump to the next version.
publish.ymlruns only after a merge. No pull request executes it.tests/publish-workflow.test.tspins its onecontents: write(inside thereleasejob) and executes theDecidestep against a stubgit(tagged → no release, untagged → release);.dev/floor/check-run-pins.test.mjspins the oneid-token: write. The first real run of any other change to the workflow (its triggers, job graph, registry check) is the next release.- Queued runs can be superseded. GitHub keeps one pending run per concurrency group. If several version bumps merge while a release is running, only the newest waiting run survives, and an intermediate version may never be published. Its CHANGELOG section then describes a version npm never had.
- No click between merge and npm. While the
npm-publishenvironment has no required reviewers, merging a bump publishes it. To add a manual approval, set a required reviewer on the environment (repository Settings → Environments →npm-publish); thepublishjob then waits for an approval in the Actions run. - The Trusted Publisher is not tied to the trigger. It is configured for the
workflow file
publish.ymland thenpm-publishenvironment, which this flow keeps; nothing in this repository can check the npmjs.com side, so the first release after this change is also the test that it accepts apush-triggered run.
- GitHub Actions — the
publishworkflow run for the merge is green, and the Releases page showsvX.Y.Zwith the CHANGELOG section as its notes. - npmjs.com — https://www.npmjs.com/package/@pharn-dev/pharn shows the new version, and that version shows a provenance badge linking back to the GitHub Actions run.
- Smoke-test —
npx @pharn-dev/pharn@latest --versionprints the new version.
npm only lets you configure a Trusted Publisher on a package that already
exists. So the very first publish of a brand-new package name is done
manually and locally by a maintainer who is logged in (npm login):
npm publish # provenance stays off (publishConfig.provenance: false) — no OIDC available yetThen configure the Trusted Publisher on npmjs.com (workflow publish.yml,
environment npm-publish), and every subsequent release goes through
publish.yml as described above. This exception applies only to introducing
a new package name — never to a normal version bump of @pharn-dev/pharn.