Skip to content

Releasing

github-actions[bot] edited this page Nov 22, 2026 · 3 revisions

Releasing

How Spotcraft is released. What a version promises is in ADR 0019.

A Spotcraft release

  1. On a chore/release-0.2.0 branch from origin/main, set the version everywhere: node scripts/check-versions.ts 0.2.0.
  2. In CHANGELOG.md, rename Unreleased to the version and date, and add its compare link.
  3. Open a pull request into main with the changelog section as its body, and merge it once the checks pass. Tag the merge commit and push: git fetch origin && git tag -s v0.2.0 'origin/main^{commit}' -m v0.2.0 && git push origin v0.2.0. There is no other branch to merge back into: main is the only one (ADR 0042).
  4. CI verifies the tagged commit, then publishes:
    • the spotcraft image, tagged 0.2.0, 0.2 and latest (merges to main publish only sha-<short>);
    • spotcraft (the CLI) on npm (latest, or next for a pre-release), with provenance. A version already on npm is skipped, so a failed run can be re-run.
    • the bundle (ADR 0047), once the image is out: spotcraft-0.2.0.tar.gz with infra/server and remote-deploy.sh, SHA256SUMS and a build attestation. The same job creates the GitHub release with the changelog's section, or adds the bundle to one that already exists.
  5. Deploy it from the instance's own repository: with kodentuzo/hetzner, bump spotcraft.version and run Deploy. Rolling back is deploying the previous version.

An npm version can't be replaced: fix a broken one with a new patch release and deprecate the broken one (npm deprecate spotcraft@0.2.0 "Use 0.2.1").

One-time npm setup

Only the original repository (kodentuzo/spotcraft) publishes to npm; CI skips the step in forks.

  1. On npmjs.com, create the free organization that owns the CLI's scope (kodentuzo).
  2. First release only:
    • create a granular access token that can publish packages (expiry: a few days);
    • store it as the secret NPM_TOKEN in a GitHub environment named npm;
    • release as above. The first versions are published with that token and --provenance.
  3. On npmjs.com, link a trusted publisher in the CLI's package settings. The fields are case-sensitive:
    • provider: GitHub Actions;
    • organization or user: kodentuzo, repository: spotcraft;
    • workflow filename: ci.yml, environment: npm;
    • allow npm publish (newer links only allow npm stage publish unless ticked).
  4. Delete the NPM_TOKEN secret and revoke the token. From then on CI publishes through GitHub's OIDC token, with no stored secret.

Clone this wiki locally