Releasing
Documentation / Contributing · Versioning
Publishing is the one action in this repository that cannot be undone. npm allows unpublishing for 72 hours and then the version number is spent for good — it can never be reused, even for identical content. Everything here is arranged so a mistake fails the workflow rather than reaching the registry.
One-time setup#
This has to be done once, by whoever owns the npm scope, before any release can work. Until it is done a tag push runs every check and then fails at the publish step — which is the right failure, having published nothing.
1. Create the @trazum scope — done#
The org exists and all three packages are on npm as of 2026-08-13, published by hand at 1.8.0.
That first publish had to be manual, and it was not a workaround. A trusted publisher is configured on a package's settings page, and that page does not exist until the package does. So the order was: publish once with a login, then configure trusted publishing, and every release after that goes through a tag with no credential anywhere.
Kept here because it is the sequence anyone forking this into a new scope has to repeat, and because two things went wrong that are worth not repeating:
npm login # E404 on PUT means "not logged in",
npm whoami # not "no such scope" — check both
npm org ls trazum # before blaming the manifests
npm publish -w @trazum/core --access public # core first: the others pin it exactly
npm publish -w @trazum/cli --access public
npm publish -w @trazum/mcp --access publicA
404 Not Found - PUTis an auth failure. npm hides the difference between "this scope does not exist" and "you may not write to it", so the first real attempt looked like a scope problem and was an expired token.npm whoamiis the one-second check that says which.npm view404s for several minutes after a successful publish, and 1.83.0 measured how long that can be.@trazum/cliwas accepted, signed and written to the transparency log, and the registry served the previous version for twenty minutes while its two siblings from the same job were installable within seconds. The CLI's tarball is 862 kB against the MCP server's 65 kB, which is the only difference between them.Since 1.83.0 the release job waits for it:
scripts/npm-serves.mjsasks the registry's dist-tags endpoint for every publishable package until each serves the version being released, and fails the job if one never does. A release is not the momentnpm publishreturns; it is the moment a stranger typingnpm installgets whatRELEASES.mdsays they will.And the dist-tag was not that moment either. On 2.7.12 the check passed at 22:42:49 UTC and
@trazum/core's tarball answered 404 for three minutes more, sonpx @trazum/cli@2.7.12failed withE404while the job was tagging the release. The script now asks for each tarball as well, with aHEADrequest to the address an install fetches, and says which of the two it is still waiting for.npm view404s for several minutes after a successful publish. The aggregated packument propagates behind the per-version document and the tarball, so+ @trazum/cli@1.8.0on screen andnpm viewreturning 404 are both true at once. Fetchregistry.npmjs.org/@trazum%2fcli/1.8.0to check the publish actually landed; it answers first.
prepublishOnly rebuilds and runs the tests before each of the four uploads,
so a failure aborts the publish rather than reaching the registry.
Nothing extra is needed to make the packages public, and there is nothing to
get wrong here. A scoped package is restricted by default, so all four manifests
carry publishConfig.access: "public" and all four publish steps pass
--access public. Belt and braces on purpose: the failure they prevent is not
a loud one. On a free account a missing --access public fails the publish,
which is fine; on a paid account it succeeds and uploads a package nobody
outside the org can install — a release that looks completely normal, for an
open-source project, and unpublishable after 72 hours.
publish.test.js asserts both of those, asserts that apps/web stays private: true
so an application never reaches a registry, and derives the set of publishable
workspaces from the root workspaces globs — so a workspace added later has to
make the choice rather than inherit one.
If the org's default visibility is set to private, leave it: the per-package
access setting is what decides, and it is already committed here.
2. Create the release environment — done#
Repository Settings → Environments → New environment, named exactly release.
Twenty seconds, and no configuration needed inside it.
This one is already in place, and it has been exercised: a
workflow_dispatch run went green through verify and npm pack --dry-run
with all four publish steps correctly skipped. If the environment were missing
or gated, the job would have sat in waiting before running anything, so a run
that starts at all is the proof.
Do this rather than relying on the workflow to bring it into existence. It is also where a required reviewer goes if you ever want publishing to need a second pair of eyes — the environment gate runs before the job starts, so an approval there blocks the publish rather than interrupting it halfway.
Since 2026-11-19 the environment is stated in the repository, with a
required reviewer. .github/environments.json holds release beside
staging and production (the web app's), each with its reviewers, the
branches and tags that may use it, and the names of its secrets, never their
values. npm run environments compares GitHub with the file, and
npm run environments -- apply --yes, run by an admin with their own gh,
makes GitHub match it; the weekly Repository settings run compares and never
writes, the way it does for the branch ruleset. release admits any branch on
purpose: a dry run from a release pull request's branch is how the token is
checked before the merge (below), and that run needs the environment too. With
a reviewer on it, every run of the Publish to npm job waits for an approval,
the dry runs included, and decide does not, so an ordinary merge to main
queues behind nothing.
3. Configure this repository as a trusted publisher — the token is what publishes#
Read this first. On 2026-08-29 the merges of the 1.85.0 and 1.86.0 release PRs each published all four packages through the workflow, with provenance, and created the tag and the GitHub release with no human step. That makes the standing instruction below — assume tags will not publish and release by hand — wrong. Releases go through the workflow now. What still does not work is the trusted publisher itself, which is the next paragraph.
Which credential authenticated the upload: the token, not OIDC. That was
left open at 1.85.0 and 1.86.0 answered it. Provenance is signed with the job's
OIDC identity either way, so the signed attestation proves nothing about the
auth — the Can this workflow authenticate to npm? step is the only thing that
does, and on
the 1.86.0 run
it reported:
npm refused the OIDC token for
@trazum/cli,@trazum/core,@trazum/mcp,@trazum/tokenizer-openai. Trusted publishing is not configured, or a claim does not match.
All four rejected, and all four published in the same job seconds later. The
only other credential in that job is the granular token on the release
environment, so the token is what is holding releases up and trusted
publishing is still not working. Do not delete the fallback.
That also settles the thing 1.85.0 only narrowed. The token was made when three
packages existed and @trazum/tokenizer-openai published anyway; the two
explanations were OIDC or a wider scope than the instruction below describes.
OIDC is now ruled out for that package by name, so the token's scope is wider
than three packages. Worth knowing before trusting the instruction that says
to list packages by name — and it does not remove the rule below about
regenerating the token when a package is added, because a scope nobody has
inspected is not a scope anybody can rely on.
Read from the run page's annotation, not from the step's job summary table.
The summary is the better artefact and it is where the per-package verdicts are
written, but the annotation is what a fetch of the run page actually returns —
so that is where this quote comes from, and it is the same sentence the warning
in checkAuth composes.
The history that follows is kept because it is what the fix has to survive, not because it is still the current state.
It failed on six real publish attempts across three versions:
1.8.0 because the packages did not exist yet, 1.9.0 because this had not been
done, and v1.11.0 four times on 2026-08-19 — after the settings had been
reported filled in. Every one of those releases that shipped went out by hand,
and none has provenance as a result. 1.25.0 was the last of those: published
from a clean clone of the tag, with the workflow's own preflight and verify
run first by hand. Since then the token fallback (below) authenticates the
workflow's own publishes, so a broken trusted publisher no longer forces a
release onto a laptop.
The v1.11.0 failures settled one thing the 2026-08-13 attempt could not: the
GitHub side is not the problem. The failing run prints the claims its token
actually carried, and all of them matched what these instructions say to type —
repository Davmunrey/Trazum, user Davmunrey, workflow release.yml, an
environment present. The mismatch, whatever it is, lives on npm's side of the
form: a configuration that did not save, saved onto the wrong package, or an
account-level restriction this document does not know about. Until someone
confirms the four package pages display a saved trusted publisher — not that
the form accepts one — assume tags will not publish and release by hand (see
Releasing by hand, below).
For each published package — @trazum/core, @trazum/cli, @trazum/mcp
and @trazum/tokenizer-openai — on the package's npm settings page under
Publishing access → Trusted publisher, enter exactly:
| Field | Value |
|---|---|
| Publisher | GitHub Actions |
| Organization or user | Davmunrey |
| Repository | Trazum |
| Workflow filename | release.yml |
| Environment | release |
The environment field is not optional here. .github/workflows/release.yml
declares environment: release, so the OIDC token GitHub mints carries that
claim. If npm's configuration leaves the environment blank while the token
asserts one, the claims do not match and the publish is rejected — with an error
about the token rather than about the mismatch, which is a confusing hour if you
do not know to look for it.
Check it without spending a version. Run the release workflow from the
Actions tab — workflow_dispatch is dry-run only — and read the Can this
workflow authenticate to npm? step. It asks npm's token-exchange endpoint the
same question the upload steps ask it, once per package:
configured @trazum/cli
rejected (404) @trazum/core
configured @trazum/mcp| Verdict | It means |
|---|---|
configured | Every claim matched for that package. |
rejected (401/403/404) | Not configured for that package, or a claim does not match. |
unknown (…) | Something else answered. Tag if you like; the upload is still the authority. |
Per package, and it is listed per package because that is how it goes wrong.
The trusted publisher is a setting on three separate pages, so configuring two of
them is the easiest mistake available — and the release publishes @trazum/core
first, so the package that fails is not necessarily the one you last looked at.
On a refusal the step also prints the claims the token carries:
The token this run carries:
repository: Davmunrey/Trazum
workflow_ref: Davmunrey/Trazum/.github/workflows/release.yml@refs/tags/v1.9.0
environment: releaseCompare each against what you typed into npm. environment: (absent) is the
answer whenever it appears — the claim exists only when the job declares an
environment, so a rule requiring release can never match a token without it.
Until this existed the only way to test a trusted publisher was to spend a version number on it, which is why 1.9.0 found out the expensive way.
Why it only reports, and when to disbelieve it. The exchange endpoint is
npm's own plumbing rather than a documented API — how to call it was worked out
by probing. So a rejected verdict has two possible causes and the check cannot
tell them apart: the configuration is wrong, or the request is. If you have
filled in all three settings pages and it still says rejected, believe the
settings. Tag, and let the publish answer — a tag that fails publishes
nothing, which is the same position as not having tagged.
That is also why it never gates. A gate built on a guess would one day block a release that would have worked, and that is worse than the failure it prevents. What it buys is a chance of knowing before you tag, not a verdict.
With a working trusted publisher there would be no token to paste and none
to rotate, and that was the whole design: a long-lived NPM_TOKEN is the
highest-value credential this project holds, and unlike every other secret a
leak is not recoverable by rotation alone, because whatever was published
under it stays published. That is not where this repository is. A token on the
release environment is what uploads today, it expires, and
The token fallback is the section to read: what holds
it, how its expiry is known in advance, and what to do the day it lapses.
Cutting a release#
Most of it is one command (since 2.7.0):
git fetch --tags
node scripts/prepare-release.mjs 2.7.0 --dry-run # what would change
node scripts/prepare-release.mjs 2.7.0 # change itIt moves every version that has to move in lockstep (the root, the six
workspaces, each workspace's @trazum/core pin, the lockfile,
packages/mcp/server.json, the plugin manifest and the MCP handshake),
folds the files in changes/ under the version's heading in CHANGELOG.md
and deletes them, moves the
"on npm at" line at the top of RELEASES.md, writes the version's
pricing dataset with its changelog and schema into
apps/web/public/datasets/pricing/ from the catalogue as built (so run
npm run build first; it refuses without one, and refuses to rewrite a
version already published), and moves the
Action pin in every document to the newest tag that exists. Every
replacement is counted, and a count that differs from what a file is known to
hold stops the run before anything is written, so a manifest added later is a
refusal, not a version left behind. What it leaves for you is prose and
prices, and it prints that list at the end. node scripts/prepare-release.mjs --pin-only moves the pin on its own.
The pin rule is what removes the follow-up PR: the docs-pin guard allows one release of lag, and the newest existing tag is always within one of the release being cut, so a pin moved in every release PR never falls out of the guard. Before this, the pin moved in a separate PR after each release, and when two releases went by without it, the guard held every open pull request red for three weeks.
Between releases, the weekly scheduled CI run calls
node scripts/freshness.mjs, which fails when a provider's price review is
past the 45-day line or the pin is two releases behind, and reports unreleased
commits. On pull requests the same report goes to the job summary without
failing, so a stale price review never blocks unrelated work.
The same weekly run reads the pricing pages themselves.
node scripts/price-drift.mjs fetches Anthropic's and OpenAI's pricing pages
in their Markdown form and compares every published figure with the catalogue:
input, output, cache hits, both cache writes, batch, the long-prompt bands
with their own cache writes, the rows OpenAI's specialised table splits into
"(short context)" and "(long context)", Anthropic's fast mode, its data residency multiplier (the generation it
starts at and the multiple, against every Claude row) and its web search fee
(the dollars per 1,000 searches, against every Claude row). A changed price is
drift, a model on the page that
the catalogue lacks is missing, and a page whose tables are no longer where
the script looks is unread; each fails the scheduled run, and on any
other run the report is printed in the step's log without failing. Freshness says
how long ago a provider was read; this says whether its page still agrees.
It never writes a price: a finding is a reason to re-read the page and change
packages/core/src/pricing.ts by hand, with the page quoted. A model left
unpriced on purpose goes in DELIBERATELY_UNPRICED with its reason, and is
reported as a note on every run. Google, DeepSeek, Moonshot, xAI and Mistral
publish no page a script reads reliably, so they stay with freshness and a
person, and with the cross-check below. --report never fails;
--anthropic-file and --openai-file run it on saved copies.
For those providers, the weekly run also asks LiteLLM.
node scripts/price-crosscheck.mjs reads LiteLLM's public
model_prices_and_context_window.json (on raw.githubusercontent.com, a host
trusted-hosts.test.js records as public data) and reports, per provider, a
LiteLLM chat model whose id the catalogue does not price (missing), an
input, output or cache-read rate that differs from the catalogue's (differs,
with the catalogue's source page and the date it was read printed beside it),
and a LiteLLM file with nothing for a provider (unread). A LiteLLM rate that
equals the row's base, its rate in force or any of its tiers (DeepSeek's peak
hours) counts as agreement and is a note naming the tier, and a retired row is
not compared. Names are matched
exactly, after taking off LiteLLM's own provider prefix, and never by
resemblance: a catalogue model LiteLLM does not list is a note. LiteLLM is a
signal, not a source. Nothing is copied, the script never writes a price or a
file, and a finding means re-read the named page. On the schedule a differing
rate or an unread file fails the run and a missing model does not, because
LiteLLM lists retired, experimental and free models the catalogue leaves out on
purpose; on any other run the report is printed without failing. A row a person
re-read and found right goes in CONFIRMED_DIFFERENCES with the page and the
date, and is reported as a note. --litellm-file runs it on a saved copy.
It also reads each provider's lifecycle. Anthropic's deprecations page has
one table of every model's state, and each OpenAI model page opens with a
Status: line when the model is deprecated or shut down and gives its context
window. A model the provider marks deprecated, retired or shut down that the
catalogue still recommends is a status finding, and a context window that
differs from the page is drift; both fail the scheduled run. It exists because
the catalogue recommended GPT-5, mini and nano for weeks after their pages said
"Status: Deprecated". --anthropic-lifecycle-file and --openai-models-dir
run it on saved copies.
The steps below are what the script does and what it leaves, in order.
Which number first. Since 1.50.1 the version carries the narrative: a chapter of the arc in progress is a patch, and the minor is spent only on the release that lands the arc's thesis. A pricing correction is also a patch, and the changelog entry is what tells the two apart. The full reasoning, including what it costs a reader pinning with a tilde, is in VERSIONING.md.
Fold
changes/intoCHANGELOG.mdunder the new version heading, and delete the files:prepare-release.mjsdoes it. Per CONTRIBUTING.md, a change that alters nothing installable still has an entry, so this is every change since the last release.Move the
ROADMAP.mdentry fromNexttoReleasedinHISTORY.md, and say what actually shipped rather than what was planned — they differ more often than they should.Bump the root and all six workspace manifests —
packages/core,packages/cli,packages/mcp,packages/tokenizer-openai,apps/webandapps/vscode— plus every workspace's pinned@trazum/coredependency and the lockfile. The web app and editor extension remain private to npm.publish.test.jsfails if they disagree, which is how the missing third one was found: this list said two for as long as the web app has depended on core, and every release that followed it leftapps/webresolving a registry copy until the guard caught it. The Claude Code plugin manifest joins the lockstep:plugin/.claude-plugin/plugin.jsoncarries the same version, held byclaude-plugin.test.js— a plugin claiming one version over a CLI at another would describe commands that behave differently than its skill says.packages/mcp/server.jsonjoins it, held bypublish.test.js: the MCP registry hosts metadata rather than artefacts, so a stale version there advertises a server that is no longer the one on npm, and a stranger is the one who finds out.Move the action pin (the script does this) to the newest existing release commit, with its version in the trailing comment.
security.test.jsasks git what version that commit declares and fails if the label disagrees — so the pin can only be advanced once the commit it names exists, which is after the merge rather than in it.Nothing to drop any more. The "not published yet" notes are gone, and
publish.test.jsnow asserts they stay gone rather than keying on a tag. That guard used the tag as a proxy for "on npm" and the manual first publish broke it: no tag was pushed, so the repository went on telling visitors nothing was installable while three packages sat on the registry. Publication does not reverse, so the assertion is one-directional now.Sweep every
.mdin the repository — the standing rule: a release is not cut until all the documentation says so. Three of them are enforced bypublish.test.js(RELEASES.mdmust have the version's section,CHANGELOG.mdits heading,HISTORY.mda mention), soverifyfails a release prep that skipped them. The rest is a two-minute grep for what the tests cannot know is stale: Update the handshake version inpackages/mcp/src/index.tstoo.packages/mcp/test/server.test.jsstarts the real stdio server and checks its announced version against the package manifest; no runtime manifest access is added to the server.git grep -nE "<previous version>" -- '*.md' ':!CHANGELOG.md' ':!RELEASES.md'Anything that surfaces is either history (fine where it is) or a claim about the present (update it). The README's action pin is the known straggler: it can only advance to the release commit after that commit exists, so it moves in the next PR —
security.test.jskeeps the label honest either way.Check the prices, per provider. The one set of numbers in this product that cannot be derived from anything in the repository.
PROVIDER_REVIEWEDinpackages/core/src/pricing.tscarries a date per provider; open the pricing page for any provider whose date is more thanSTALE_PRICING_DAYSold, compare every model this table prices, and move that provider's date only if you actually looked. The catalogue's headline date is derived as the oldest of the seven, so a partial review records itself honestly instead of overstating the rest.Two things
pricing-review.test.jswill catch and one it cannot. It catches a promotion that expires before the next review is due — a price change this table can see coming, and the reason Sonnet 5 nearly went out 50% too high — and it catches a review date in the future or a provider priced with no date at all. It cannot catch a provider quietly changing a price, which is what this step is.And ask whether the models still exist, which is a different question from whether the prices are right and was unasked for eighty releases:
ANTHROPIC_API_KEY=... OPENAI_API_KEY=... npm run check:modelsIt sends one real request per priced model and rewrites
packages/core/test/fixtures/model-availability.json; commit what it writes. The first run found four ids the provider refuses outright, two of which that provider's own model list still returns. Any key you have is worth using and any you lack is recorded as unasked, so a partial run is honest rather than reassuring. A newly refused model is markedretiredin the provider's own words and keeps its price, because the calls in somebody's log really happened; what it costs to move off it is a price, and comes off the provider's page under the step above or not at all.npm run verify, and read the exit code rather than the output. The agent suite includes the synthetic task stress probes documented in Contributing. Runnpm run verify:packagesto pack the public workspaces, install their tarballs together in a temporary directory and rerun the stress probes against that installation. CI and the release workflow both require this check before publication. This catches missing package files and workspace-only resolution. Thennode scripts/adoption.mjsand paste the line it prints under the new heading inRELEASES.md. Three public counters — npm downloads of@trazum/cliover the last thirty days, GitHub stars, the MCP registry's latest version — read once and written beside the version, so the next plan starts from a figure the waydocs/plan-2.4.mddid. A counter the network would not give is printed as unavailable, never as zero; leave it that way rather than filling it in from memory.Merge. That is the release. The push to main triggers the workflow's
decidejob, which sees a manifest version the registry does not have and hands it to the release job: verify again, publish all four packages, create thev<version>tag on the merge commit, and publish the GitHub release fromRELEASES.mdwith the bill of materials attached. Then a third job waits for npm to serve the new@trazum/mcpand updates the MCP registry listing, which was the last manual step until 1.80.2. No tag to type, no second step to remember.If the packages published and the tag or the release did not, push the tag yourself on the release commit, and the tag-triggered run skips the uploads (every version is already on npm) and creates the release:
git tag v2.7.2 <release commit> && git push origin v2.7.2That is what 2.7.2 needed. A pull request that changed a comment in
ci.ymlmerged while the Release run was publishing, and GitHub refuses the workflow's token any ref whose.github/workflows/files differ from main's: GITHUB_TOKEN can never hold theworkflowspermission that would allow it. The failed step now says so and prints the command. Don't merge a pull request that touches.github/workflows/while a Release run is in progress, and it does not happen.backfill-releasescan create one missing release from itsversion,commitandlatestinputs, but only while that commit's workflow files still match main's.When the tag is pushed days later, the run it starts may fail at Verify, and that is expected. A tag-triggered run checks out the tagged commit and verifies that tree before it creates the release, and some of this repository's tests fail by the calendar: a promotional price in its last 45 days, a provider review past its window. 2.7.2's tree has failed the first of those since 2026-11-16, so its tag gives a failed Release run and no release page. Nothing is published either way, because every version is already on npm. Finish it from the Actions tab: run
backfill-releaseswith the version, the release commit andlatestoff. It finds the tag, skips the push it would be refused, and creates the release fromRELEASES.md.Only the tag itself needs a person. The workflow's token is refused the ref for as long as the commit's workflow files differ from main's, and an agent session can neither push a tag nor create one through the GitHub tools it is given.
A pushed tag still works as the manual override — for re-running a release whose publish failed, or releasing a commit that is not the newest merge:
git tag v1.2.0 <commit> && git push origin v1.2.0
The workflow does the rest. It will refuse if the tag and the manifests disagree,
and it runs the same verify a pull request runs before anything is published —
a release gate that checks less than the pull-request gate lets through exactly
what the tag was for.
Every GitHub release carries a bill of materials, from the first release
after 2.7.7: trazum-v<version>.cdx.json, a CycloneDX 1.5 document listing
each workspace and every third-party package any of them needs at run time,
with its version, licence, purl, hash and tarball, and what depends on what.
The release job writes it with scripts/sbom.mjs before anything is uploaded,
and the script checks the document before writing it, so a bill that fails
stops the release while nothing is published. It is read from the lockfile
rather than made by npm sbom --omit dev, which on this tree leaves out seven
packages a runtime dependency needs whenever a development tool needs them as
well. test/sbom.test.mjs makes the same document on every pull request and
requires it to hold everything npm ls --omit dev and npm sbom find. To make
one yourself: node scripts/sbom.mjs trazum.cdx.json. A release created by
hand or by backfill-releases has none: that workflow runs on main's tree,
whose lockfile is not the old commit's, so a bill made there would describe
the wrong release.
@trazum/core publishes first. The CLI and the MCP server depend on it at an exact version, so the
other order leaves a window where installing the CLI fails on a dependency that
does not exist yet.
A next prerelease#
A next is a build of what is coming, on npm, for whoever asks for it:
npm install @trazum/cli@next. It never moves latest, which is what
npm install @trazum/cli resolves, and it changes nothing on the record:
no section in RELEASES.md, no heading in CHANGELOG.md, no pricing dataset,
no GitHub release, no files, no MCP registry listing.
Its version is MAJOR.MINOR.PATCH-next.N, leading up to the release it
previews: 3.1.0-next.1, then 3.1.0-next.2, then 3.1.0 itself through the
ordinary release pull request. No other prerelease word is published.
scripts/npm-channel.mjs decides the channel from the version and refuses
anything else.
git fetch origin
git switch -c next/3.1.0-next.1 origin/main
npm run build
node scripts/prepare-release.mjs 3.1.0-next.1 # the versions only
npm run verify
git commit -as -m "3.1.0-next.1"
git tag v3.1.0-next.1
git push origin v3.1.0-next.1 # the tag, not the branchprepare-release.mjs with a -next.N version moves the versions that move in
lockstep (the manifests, each @trazum/core pin, the lockfile, server.json,
the MCP handshake, the plugin manifest and the Gemini extension) and nothing
else. The documents keep naming the release on latest, and the tests that
hold a document to "the current version" read that release on a next's tree
(recordedVersion in npm-channel.mjs), so the tree passes the same verify
a release does.
The tag starts the same Release workflow as a release, and goes through the
same gate: the approval on release, the tag and the manifests agreeing, the
whole verify, verify:packages, the version preflight. Then each package is
uploaded with --tag next, and npm actually serves every package waits for
next to name the version and fails at once if latest does. The GitHub
release, the files and the listing are skipped.
Never merge the branch. Main's manifests name the release on latest, and
a merge to main publishes whatever version main names. A prerelease version on
main is refused by npm-channel.mjs before the job that holds the token
starts, so a merged next fails loudly rather than publishing, and the fix is to
revert the merge. The branch can be deleted once the tag is pushed: the tag
holds the commit.
What holds it, in npm-channel.test.js: the table of versions and channels; a
prerelease refused on main; a tag refused when it does not name the manifests'
version, in both directions; every npm publish in release.yml passing
--tag "$NPM_DIST_TAG" from decide; the wait for npm reading the same tag;
and the GitHub release, the assets job and the mcp-registry job gated on
latest.
If latest moved anyway, the job says so and names the command. Put
latest back on the version RELEASES.md says is on npm, for each package:
npm dist-tag add @trazum/cli@<the version RELEASES.md names> latestThe files a release carries#
Besides the packages, a release carries trazum-vscode-<version>.vsix,
trazum-mcp-<version>.mcpb, trazum-pricing-<version>.json and SHA256SUMS
(#640, #780, #784). They are built by
the assets job of release.yml, which needs the job that publishes, so it
starts after npm actually serves every package and after the GitHub release
exists; the publish order is not touched. The job holds contents: write and
no npm credential, no id-token and no environment, because it runs two
packagers fetched by npx at an exact version (scripts/release-assets.mjs
names them). A manual run of the workflow makes the files and prints their sums
and attaches nothing: do that from a release pull request's branch to know the
packagers still work before the merge.
The pricing dataset is not made in that job, only checked there. It is the
document prepare-release.mjs wrote into apps/web/public/datasets/pricing/
in the release pull request, which the site serves at the same version;
release-assets.mjs builds it again from the core the job just built and
copies the committed file only when the two are the same bytes, so the asset
and the site's file are one file under one digest. A difference stops the job
before anything is uploaded. It should not get that far: in the release pull
request the document records the pricing.ts it was built from, so
test/pricing-dataset.test.mjs compares it byte for byte with a fresh build
and fails there, which is how a document written from a dist/ older than its
source is caught before the merge. node scripts/pricing-dataset.mjs check
asks the same question locally.
The pricing dataset is the page for whoever consumes it.
If the job fails after the release exists, re-run it: the upload replaces what an earlier attempt left. The MCP registry listing waits for it and adds the bundle to what it publishes (below), so a failed attachment holds the listing back until it is re-run, and a version is never listed with a bundle that is not there.
The Homebrew formula is not part of the workflow. See "The Homebrew formula is a
manual step" in RELEASES.md.
Listing on the MCP registry#
Separate from npm, and automated since 1.80.2. The official MCP registry hosts
metadata: it records that a name maps to a package, and it verifies the claim
by fetching that package from npm and reading mcpName out of its manifest. So
the listing can only ever point at a version that is already published, which is
what shapes the job.
release.yml has an mcp-registry job that runs after the npm publishes:
scripts/mcp-registry-preflight.mjsasks npm for the exact version until it answers 200 and serves the rightmcpName, up to five minutes.mcp-publisheris downloaded at a pinned version and checked against the checksum published for that tag.mcp-publisher login github-oidcexchanges the job's OIDC token for a registry token. No stored credential: the registry grants the namespace matching the token'srepository_ownerclaim.mcp-publisher publishsendspackages/mcp/server.json.- The job then asks the registry what it now serves, and fails if it is not the version just sent.
Three deliberate choices, each paid for.
- A separate job, not a step in the release job. It downloads a third-party
binary and runs it, in a process that can mint a token for the whole
io.github.<owner>/*namespace. Keeping it out ofenvironment: releasemeans that binary never shares a process withsecrets.NPM_TOKENor withcontents: write. By the time it runs, npm and the GitHub release are done, so the worst it can do is fail, and a failed listing is recoverable by hand. - The publisher binary is pinned by version and checksum, not fetched from
releases/latest/downloadas the upstream guide shows. Same rule as every action in this repository. The cost is a maintenance edge: when the registry rotates its OIDC audience, an old binary fails withinvalid audienceand the fix is to bumpMCP_PUBLISHER_VERSIONandMCP_PUBLISHER_SHA256together, taking the checksum fromregistry_<version>_checksums.txton that release. The job's failure note says exactly that, because the error names nothing that would lead you here. - The wait is a poll, not a sleep. npm serves a new version minutes after the publish returns, and chaining the two publishes without waiting produces a 400 that reads like a manifest bug and is a propagation race. A fixed sleep is either too short on a slow day or too long on every other day.
security.test.js holds all of it: the job exists, it is gated on the same
decision the uploads are, it waits before it publishes, the binary is pinned and
verified, and the job is not in the release environment.
Publishing the listing by hand#
Still the fallback when the job fails, and the only route for a listing that has to move without a release:
cd packages/mcp
mcp-publisher login github # device flow, opens a code in the browser
mcp-publisher publish # reads ./server.jsonFour things that cost real attempts:
Do not run
mcp-publisher init. It writes aserver.jsonnamed after the directory,io.github.<user>/mcp, overwriting the one this repository keeps in the version lockstep. The committed file is the source of truth; if it is missing, the checkout is stale, not the tool.The namespace is case-sensitive. GitHub authentication grants
io.github.<login>/*with the login spelled exactly as GitHub spells it, soio.github.davmunreyandio.github.Davmunreyare two different namespaces and only one of them is yours. Getting this wrong returns a 403 that quotes both strings, and it cost 1.80.1: the correctedmcpNameonly counts once it is on npm, so the fix was a release.publish.test.jsnow derives the owner fromserver.json's repository URL and holds both files to it.A 400 saying the package is "missing required
mcpNamefield" means the versionserver.jsonadvertises does not carry that field on npm, usually because the manifest was edited after the last publish, or because npm has not propagated yet. Check what the registry sees before blaming the login:curl -s https://registry.npmjs.org/@trazum%2fmcp/<version> | grep mcpNameA 401 saying the token is expired is exactly that. The device-flow credential is short-lived;
mcp-publisher login githubagain and republish.
The token fallback#
The publish steps authenticate with OIDC when nothing else is configured, and with an environment-scoped npm token when one is — the fallback that keeps a merge from failing while npm's trusted publishing stays broken. Setting it up, once:
On npm (as the account that owns
@trazum): Access Tokens → Generate New Token → Granular Access Token. Permissions Read and write, scoped to only the@trazumpackages this repository publishes, with an expiry — 90 days is a fine default. Do not create a classic automation token; granular is the one whose blast radius is those packages instead of the account.It must be allowed to publish without a one-time code. The account protects publishing with two-factor authentication, a workflow has no authenticator, and a token made without that allowance authenticates and is then refused the upload with
EOTP. The first replacement token on 2026-11-17 was one of those. npm's token form has an option to bypass two-factor authentication for the token; that is the one.A package added after the token was made is not in its scope. A token listing packages by name cannot publish a fifth one and cannot create it, and the failure is the same
E404as a missing trusted publisher, on the package nobody was looking at. Whenever this repository starts publishing a new package, regenerate the token with it included and update the secret, in the same change that adds the package.On GitHub: Settings → Environments → release → Environment secrets → Add secret, name
NPM_TOKEN, value the token. An environment secret on purpose: only jobs that enter thereleaseenvironment can read it, which is exactly one job in one workflow.In this repository: write the expiry date npm showed into
.github/release-credentials.json, as"expires": "YYYY-MM-DD", in a pull request of its own. The date is not a secret and the token never goes there. It is the only way anything here learns when the token lapses: npm shows the date when the token is made and this repository cannot ask for it afterwards.
What the trade costs, honestly: a long-lived credential now exists, and a
leak of it is not recoverable by rotation alone — whatever was published
under it stays published. What it does not cost is provenance: the
attestation is signed with the job's OIDC identity, which is independent of
how the upload authenticates, so releases through the workflow carry
provenance with either auth. security.test.js pins the containment: only
release.yml may reference the secret, only in the one shape, only in the
four upload steps and the two that ask npm about it, and token material
committed anywhere fails the build.
When trusted publishing finally works, delete the secret and set "expires"
back to null; the same workflow reverts to pure OIDC with no edit.
When the token expires#
npm stopped accepting it on the day of 2.7.10. The release pull request
merged on 2026-11-17, the job verified, packed and stressed the release for
five minutes, and the first upload answered E404 Not Found - PUT, under a
note that said a job holding the token had failed for some other reason.
Nothing was half-published, and main named a version npm did not have. npm's
answer does not say whether a token expired or was revoked; the fix is the
same. Three things now stand between a lapsing token and that state:
Two weeks ahead.
node scripts/freshness.mjsreads the recorded date and calls it overdue from fourteen days before, which turns the weekly scheduled CI run red onmain, where GitHub notifies the owner. A date nobody recorded is printed as a note that says so, on every run.Before the release is prepared.
node scripts/prepare-release.mjsrefuses to prepare a release once the recorded date has come, and lists a near or unrecorded date among what is still yours. A dry run says what a real run would refuse.At the start of the job. Is the stored npm token still alive? asks npm
whoamiwith the token beforeverify, and on a manual dry run too, so a dry run from a release pull request's branch answers before the merge. A refusal is an error on the run page and in the job summary, with the steps below, and the failure note at the end of the job asks again and ends on the answer.It reports and does not fail. Measured against the live registry on 2026-11-17: a token npm does not know is answered
401, and so was the token stored on thereleaseenvironment, 42 minutes after it failed 2.7.10's upload (the dry run). The token that replaced it was answered200the same afternoon. What keeps the step a report is the trusted publisher: if npm ever accepts it, an upload needs no token, and a gate on a dead one would stop a release that would have gone out.An accepted token is not a promise, and that was measured the same day too. Thirteen minutes after that
200, the first upload with the new token answeredEOTP, "This operation requires a one-time password from your authenticator": the account asks for a code to publish and the token had not been made to publish without one.whoamicannot be asked that, nor whether the token may write to each package.
Renewing it, which only the owner of the npm account can do:
- Generate a new granular token as in step 1 above, with all the
@trazumpackages in its scope. - Replace the
NPM_TOKENsecret on thereleaseenvironment. - Record the new expiry date in
.github/release-credentials.json.
If a release pull request has already merged, do not merge anything else
first. Re-run the failed jobs of that release's run: it is pinned to the
release commit, so it uploads exactly the tree its notes describe. Every push
to main starts a publish attempt for whatever version the manifests name, so
a merge between the failure and the re-run is tried again with the dead token,
and re-running that later attempt once the token is renewed would upload the
later tree under the release's number and notes.
Releasing by hand#
The last resort — for when the workflow itself is broken, not just npm's authentication (the token fallback above covers that without leaving GitHub). It is the exact procedure 1.25.0 used, before the fallback existed. The cost is stated first because it is the only one: a manual publish carries no provenance attestation — nobody can verify the tarball was built from this repository at this commit. Users notice nothing.
Publish from a clean clone, never from a working tree — a local checkout can be
behind, dirty, or missing files, and what npm publish packs is whatever is on
disk:
cd /tmp && rm -rf trazum-release
git clone --depth 1 https://github.com/Davmunrey/Trazum.git trazum-release
cd trazum-release
node -p "require('./package.json').version" # read it: this is what ships
npm ci
node scripts/npm-publish-preflight.mjs versions # aborts if any number is spent
npm run verify
npm whoami || npm login # and `npm logout` when done
npm publish -w @trazum/core --access public # core first: the others pin it exactly
npm publish -w @trazum/cli --access public
npm publish -w @trazum/mcp --access publicThen push the tag by hand (this is the one path where the tag comes second),
and let the workflow create the GitHub release — its preflight sees the
versions on the registry and skips the uploads. Two
reminders from doing this for real: npm view 404s for several minutes after a
successful publish (fetch registry.npmjs.org/@trazum%2fcore/<version> to
check instead), and npm logout afterwards revokes the session token, which is
the closest a manual publish gets to not holding a credential.
Checking a release without publishing one#
Run the workflow from the Actions tab. workflow_dispatch is dry-run only —
every publish step is gated on a tag, so a manual run does the install, the
verify, the npm pack --dry-run and the bill of materials, and stops. A publish reachable without a
tag would be a release with no version to check against.
A dry run also says which channel a tag of that tree would publish to,
latest or next, in Which npm channel? and on its last line.
Two of its first steps are about credentials and are worth a dry run on their
own: Can this workflow authenticate to npm? (the trusted publisher) and Is
the stored npm token still alive? (the token that actually uploads). Run it
from a release pull request's branch before merging and the second one says
whether the merge can publish. The run page shows it as an annotation, and the
last line of the job's own script repeats it as one word (accepted,
refused, absent or unknown), because the end of the log is what the API
returns and the step itself is forty thousand lines above it.
If something goes wrong#
The tag was wrong — nothing was published, because the version check runs before
verify. Delete the tag, fix it, tag again.E404 Not Found - PUT— an authentication failure, not a missing package. npm reports a write you are not authorised for as "not found", which is why this cost an hour at the first publish and reappeared at 1.9.0 and at 2.7.10. The failed job ends on how npm answers each credential. If it says npm refuses the stored token, the token has expired or been revoked: go to When the token expires. If it says npm accepts the token, the package that failed is outside the token's scope: regenerate it with every package included. Step 3 is for the trusted publisher, which has not authenticated an upload yet.EOTP, "This operation requires a one-time password" — the token authenticates and may not publish without a two-factor code, which a workflow cannot supply. Generate it again with the option that lets the token bypass two-factor authentication (The token fallback, step 1) and re-run the failed job. Nothing was uploaded.@trazum/corepublished and@trazum/clior@trazum/mcpfailed — the core version is spent. Bump to the next patch across all manifests and release again rather than trying to reuse the number; npm will not let you, and a--forcethat worked would be worse.This is the shape the preflight exists to prevent: No version may already be on the registry checks all three before the first upload, so a re-tag of a half-published release aborts instead of spending another number. It cannot help with a failure that happens between two uploads — nothing can, short of a transaction npm does not offer — but that is now the only way to get here.
Within 72 hours, badly wrong —
npm unpublish @trazum/core@1.2.0. After that the version is permanent and the answer is a new one with a changelog entry saying what the bad one did.