Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

  1. version compares the tag with every literal and refuses before anything is built. A check at the end would already have spent the matrix.
  2. build runs the tests and packages one archive per target: x86_64-unknown-linux-musl, aarch64-unknown-linux-musl on an arm64 runner, aarch64-apple-darwin, x86_64-apple-darwin on an Intel runner, and x86_64-pc-windows-msvc, each with a .sha256.
  3. npm smoke installs the assembled packages from their tarballs on four platforms and checks the wrapper answers like the binary.
  4. 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.
  5. 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).