Releasing
A release is a tag. release.yml publishes on a pushed v* tag and on nothing
else, because a release that could be produced from a branch would make “the
binary for v0.8.0” a question rather than an answer. Everything a release ships
– the archive names, the npm packages, the release title – derives from the
tag. What makes that safe is that the tree has to agree with the tag before
anything is built.
Bump the version literals
Twelve literals across eight files carry the version, and every one of them must say the version you are about to tag:
crates/ank-cli/Cargo.toml version = "<v>"
crates/ank-core/Cargo.toml version = "<v>"
npm/ank/package.json "version"
npm/ank/package.json the four optionalDependencies pins
npm/ank-linux-x64-musl/package.json "version"
npm/ank-linux-arm64-musl/package.json "version"
npm/ank-darwin-arm64/package.json "version"
npm/ank-win32-x64/package.json "version"
.claude-plugin/plugin.json "version"
You do not have to remember that list. The check that gates the release prints it, with the exact line that repairs each literal, when you hand it a version the tree does not carry:
$ bash .github/scripts/check-version.sh 0.8.1
version 0.8.1 disagrees with 10 of 10 version literals
...
repair every line above, then move the tag:
crates/ank-cli/Cargo.toml: version = "0.8.1"
crates/ank-core/Cargo.toml: version = "0.8.1"
npm pkg set version=0.8.1 --prefix npm/ank
...
and answers version 0.8.1 agrees with all 10 version literals once they are
bumped. Run it before you tag. The bump lands like any change, by pull request,
and Cargo.lock follows the two manifests on the next build.
The same script runs on every pull request against fixture trees, as the
version check job, so a bump that touched six of the seven files is red on the
branch that made it and not on the tag (CI jobs and required
checks).
Rehearse with a dispatch
release.yml also runs on workflow_dispatch, and a dispatch builds the same
five targets and publishes nothing. Run one before tagging whenever the pipeline
itself changed:
gh workflow run release.yml --ref main
The alternative is discovering that the release pipeline is broken at the moment you use it, on a tag you then have to delete, and a tag is the one thing here that is awkward to take back. On a dispatch the version job says there is no tag to compare and skips the comparison, the five builds and the four npm smoke tests run in full, and the two publish jobs do not start.
Tag
With the literals bumped and merged, tag the merge commit on main and push the
tag. The tags so far are annotated, with the version as the first line of the
message and what the release adds under it:
git switch main && git pull
git tag -a v<version>
git push origin v<version>
What the run then does, in order:
- version compares the tag with every literal and refuses before anything is built. A check at the end would already have spent the matrix.
- build runs the tests and packages one archive per target:
x86_64-unknown-linux-musl,aarch64-unknown-linux-muslon an arm64 runner,aarch64-apple-darwin,x86_64-apple-darwinon an Intel runner, andx86_64-pc-windows-msvc, each with a.sha256. - npm smoke installs the assembled packages from their tarballs on four platforms and checks the wrapper answers like the binary.
- publish creates the GitHub release from the five archives, only once every build row passed. A release carrying four targets out of five would look complete.
- publish-npm publishes the four platform packages and then the wrapper, only once every smoke row agrees.
A version with a prerelease suffix, v0.9.0-rc1, publishes under the npm
dist-tag next and as a GitHub prerelease, so it is installable by whoever asks
for it by name and never becomes what a bare npm install -g @haksolot/ank
resolves to. Anything else publishes as latest.
Trusted Publishing
publish-npm holds no npm credential. It runs with id-token: write, and npm
exchanges the job’s OIDC token for a short-lived publish credential, so
the pipeline uses no secret at all: the GitHub release is
created under the workflow’s own token, and the registry attaches provenance to
every package it receives.
npmjs.com decides whom to trust, per package. Each of the five packages,
@haksolot/ank, @haksolot/ank-linux-x64-musl,
@haksolot/ank-linux-arm64-musl, @haksolot/ank-darwin-arm64 and
@haksolot/ank-win32-x64, names GitHub Actions as its trusted publisher
under Settings → Trusted Publisher, with the owner haksolot, the repository
ank and the workflow file release.yml. Renaming that file, or adding a
sixth package, means adding the new name there before the next tag, or that
package’s publish is refused.
The same page carries Allowed actions, and it has to allow publishing
directly. npm always allows a staged publish, which waits for somebody to
approve it on the website, and adds a direct publish only when that box is
ticked. A trust left at its default answers this job with 403 Forbidden ... OIDC permission denied for this action, after the job has already signed its
provenance, so the error reads as an authentication that succeeded. Managing
dist-tags can stay off: --tag is applied by the publish itself.
A refused publish fails publish-npm alone. The GitHub release still
publishes, because the release page is the primary channel and npm a
convenience on top of it. Re-run the failed job once npmjs.com is corrected:
the rerun replays the workflow of the tagged commit, so a fix to release.yml
itself reaches npm only with the next tag.
After the release
ank update --check against the new tag should report it as latest, and the
installers read the release page directly, so both routes serve it as soon as
the release exists. Nothing else is published: no package manager ships ank
(Install says why).