Skip to main content

releasing

ROADMAP.md is the contract: what a v0.0.x tag promises (nothing beyond addressability) and what v0.1.0 has to show first. This page is the mechanics.

When a tag is cut​

.github/workflows/release.yml cuts tags itself. Every Monday at 06:17 UTC it looks at main and, if both of the following hold, tags the commit with the next patch number (v0.0.1, v0.0.2, ...) and releases it in the same run:

  • main has moved since the last v* tag. A week with nothing merged produces nothing: a tag names a build, and the same build does not need two names.
  • CI has finished on that commit and nothing failed. The Rust quality gate must have passed; a nightly-only job that was skipped is fine; a check still running means "not yet", and the next Monday asks again.

The decision is scripts/release-cut.sh, which prints what it would do when run from a checkout of main; the workflow's dry_run input runs only that. Between Mondays, workflow_dispatch cuts one on demand, and bump: minor starts a new line (v0.1.0) when ROADMAP.md's evidence for it exists. Only one release runs at a time, so a dispatch during the Monday run waits rather than racing it for the number.

A tag pushed by hand still works, and goes through the same build jobs:

git tag -a v0.0.1 -m "v0.0.1: an addressable prerelease" origin/main
git push origin v0.0.1

Either way the run then:

  • builds spindle for x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu from the tagged tree with --locked, and packages each as a tarball with the licences, the README, the example config and the systemd unit, plus a .sha256 beside it;
  • builds the runtime image (the Dockerfile at the root) for amd64 and arm64 and publishes a manifest at ghcr.io/tuna-os/spindle:<tag>;
  • uses the cargo features in FEATURES of release.yml for the tarballs and the image. Today, that is mas-import (#802) and synapse-import (#826);
  • stops if spindle import-mas or spindle import-synapse does not print its usage. The MAS cutover in delegated-auth.md and the Synapse migration in migration-workspace.md need these commands;
  • writes an SBOM for each tarball (SPDX, from Cargo.lock, so it names every crate the build pinned) and attests it to the tarball;
  • signs a provenance attestation for each tarball and each image, through Sigstore, tied to the workflow's own identity; the image attestations are pushed to the registry beside the images;
  • builds a .deb and an .rpm for each architecture from the tarball's binary, in a separate packages job (cargo-deb and cargo-generate-rpm, metadata in crates/spindle-server/Cargo.toml). It writes a checksum for each and signs a provenance attestation. This job may fail without blocking the release: the tarballs and the image still go out, without packages;
  • creates the GitHub release with the tarballs, the packages when they exist, the checksums, the SBOMs and notes that say what the tag is and give the image digest, followed by the titles of the pull requests merged since the previous tag, marked a prerelease for every v0.* tag.

The crate version in Cargo.toml is not the release version and is not bumped by a release; the tag is the name, and the binary carries the commit it was built from.

Nothing is published under latest. A tag names a build; the next tag names the next one.

Checking a build is what it says​

A file name proves nothing. The attestation does: it says which workflow, on which commit, produced the artifact with this digest, and Sigstore's log says when.

gh attestation verify spindle-v0.0.1-x86_64-unknown-linux-gnu.tar.gz --repo tuna-os/spindle
gh attestation verify oci://ghcr.io/tuna-os/spindle:v0.0.1 --repo tuna-os/spindle

--repo is the trust root: the check passes only for attestations signed by a workflow in this repository. The SBOM beside each tarball is an SPDX document; gh attestation verify --predicate-type https://spdx.dev/Document checks that it, too, was attested to the same tarball by the same workflow.

Packages​

Two scripts build and check the .deb and .rpm. scripts/build-packages.sh pins cargo-deb and cargo-generate-rpm. scripts/check-packages.sh lists the contents, checks the unit, the conffile and the licences, and runs the binary from an unpacked .deb.

The release packages job and the packages job in ci.yml call the same scripts. A pull request that changes the package files runs them on a debug build. To change a tool version, edit the script only.

The asset paths in crates/spindle-server/Cargo.toml name files under package-staging/. The script fills that directory and runs both tools from the crate directory.

What a tag gives the rest of the project​

  • Benchmarks can name the Spindle they measured, alongside the Synapse, Continuwuity and Tuwunel versions they already name.
  • SECURITY.md's "fixed in" can name the first tag carrying a fix.
  • Storage-format changes can say which tag introduced them, with the schema version the store already writes in its first byte.

Running the image​

docker run -v ./spindle.toml:/etc/spindle/spindle.toml:ro \
-v spindle-data:/var/lib/spindle \
-p 8008:8008 ghcr.io/tuna-os/spindle:v0.0.1

The image runs as an unprivileged user and expects the store under /var/lib/spindle, which [storage] path in the mounted config should name. The Complement image under complement/ is a different thing: it satisfies that suite's startup contract and is not for operators.