@@ -0,0 +1,156 @@
+name: release
+
+on:
+  # A tag is a release: it gets a version number, release notes, and a URL
+  # that keeps meaning the same thing a year from now.
+  push:
+    tags:
+      - "v*"
+  # main is the rolling channel. kuma is consumed by rebuilding constantly,
+  # so waiting for a tag to get a usable binary would mean the published
+  # one is nearly always behind the tree it is meant to build from.
+  branches:
+    - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  # Keyless signing: cosign trades this token for a short-lived certificate
+  # instead of anyone holding a private key.
+  id-token: write
+
+env:
+  CARGO_TERM_COLOR: always
+  TARGET: x86_64-unknown-linux-musl
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: work out what this build is
+        id: what
+        run: |
+          set -euo pipefail
+          version=$(cargo metadata --no-deps --format-version 1 \
+            | jq -r '.packages[] | select(.name == "kuma") | .version')
+          # The asset name carries no version on purpose. A versioned
+          # filename would make releases/latest/download/<name> change
+          # every release, so the README could never hold a durable URL,
+          # and the version is not lost: the tag has it and the binary
+          # reports it.
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            # A tag that disagrees with Cargo.toml would publish a binary
+            # whose own --version contradicts the release it sits in. That
+            # is the exact class of lie the build stamp exists to prevent,
+            # so it fails here rather than shipping.
+            if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
+              echo "tag ${GITHUB_REF_NAME} does not match Cargo.toml version ${version}" >&2
+              exit 1
+            fi
+            {
+              echo "tag=v${version}"
+              echo "name=kuma-${TARGET}"
+              echo "prerelease=false"
+              echo "title=kuma v${version}"
+            } >> "$GITHUB_OUTPUT"
+          else
+            {
+              echo "tag=latest"
+              echo "name=kuma-${TARGET}"
+              echo "prerelease=true"
+              echo "title=Rolling build from main"
+            } >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: x86_64-unknown-linux-musl
+      - uses: Swatinem/rust-cache@v2
+
+      # ci.yml runs on this same push, but nothing makes this job wait for
+      # it, so without a gate here a red tree still publishes a binary.
+      # Testing on the release target rather than the host's costs nothing
+      # extra: it is one compile instead of two, and it exercises the
+      # artifact actually being shipped.
+      - name: test
+        run: cargo test --locked --target "$TARGET"
+
+      # Static by construction, not by flag: kuma is pure Rust with no NSS
+      # calls and no in-process networking, so a musl build has nothing to
+      # dynamically link. That is what lets it run on an image-based
+      # desktop that has podman and no toolchain, which is the machine
+      # most likely to want it.
+      - name: build
+        run: cargo build --locked --release --target "$TARGET"
+
+      - name: package
+        id: pkg
+        run: |
+          set -euo pipefail
+          name='${{ steps.what.outputs.name }}'
+          cp "target/${TARGET}/release/kuma" "$name"
+          strip "$name"
+          sha256sum "$name" > "${name}.sha256"
+          # Prove the artifact runs before publishing it. A binary that
+          # cannot answer --version on a clean runner is not a release.
+          "./$name" --version
+          echo "name=$name" >> "$GITHUB_OUTPUT"
+
+      - uses: sigstore/cosign-installer@v3
+
+      - name: sign
+        run: |
+          set -euo pipefail
+          cosign sign-blob --yes \
+            --output-signature '${{ steps.pkg.outputs.name }}.sig' \
+            --output-certificate '${{ steps.pkg.outputs.name }}.pem' \
+            '${{ steps.pkg.outputs.name }}'
+
+      # The rolling release is one moving target, so its old assets and tag
+      # are cleared first. Deleting the tag matters: gh reuses an existing
+      # one and the release would keep pointing at the commit it was first
+      # cut from.
+      - name: clear the rolling release
+        if: steps.what.outputs.tag == 'latest'
+        run: |
+          gh release delete latest --yes --cleanup-tag || true
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: publish
+        run: |
+          set -euo pipefail
+          gh release create '${{ steps.what.outputs.tag }}' \
+            --title '${{ steps.what.outputs.title }}' \
+            --notes "$(cat <<'NOTES'
+          Static `x86_64` binary, no runtime dependencies.
+
+          ```console
+          $ curl -LO ${{ github.server_url }}/${{ github.repository }}/releases/download/${{ steps.what.outputs.tag }}/${{ steps.pkg.outputs.name }}
+          $ chmod +x ${{ steps.pkg.outputs.name }} && sudo mv ${{ steps.pkg.outputs.name }} /usr/local/bin/kuma
+          ```
+
+          Verify it came from this workflow:
+
+          ```console
+          $ cosign verify-blob \
+              --certificate ${{ steps.pkg.outputs.name }}.pem \
+              --signature ${{ steps.pkg.outputs.name }}.sig \
+              --certificate-identity-regexp '^${{ github.server_url }}/${{ github.repository }}/' \
+              --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+              ${{ steps.pkg.outputs.name }}
+          ```
+
+          Built from `${{ github.sha }}`.
+          NOTES
+          )" \
+            ${{ steps.what.outputs.prerelease == 'true' && '--prerelease' || '' }} \
+            --target '${{ github.sha }}' \
+            '${{ steps.pkg.outputs.name }}' \
+            '${{ steps.pkg.outputs.name }}.sha256' \
+            '${{ steps.pkg.outputs.name }}.sig' \
+            '${{ steps.pkg.outputs.name }}.pem'
+        env:
+          GH_TOKEN: ${{ github.token }}
@@ -1,6 +1,6 @@
 [package]
 name = "kuma"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 # Set by sha-crypt 0.6, the highest floor anything here asks for. Without
 # it, an older toolchain fails somewhere inside a dependency instead of
@@ -10,6 +10,13 @@ description = "Declarative, atomic Fedora bootc system"
 license = "MIT"
 repository = "https://github.com/Letdown2491/kuma-linux"
 
+# cargo-binstall fetches the release asset instead of compiling. Its
+# default URL patterns expect the version in the filename, which kuma's
+# assets deliberately omit, so the pattern is spelled out.
+[package.metadata.binstall]
+pkg-url = "{ repo }/releases/download/v{ version }/kuma-{ target }"
+pkg-fmt = "bin"
+
 [dependencies]
 anyhow = "1"
 clap = { version = "4", features = ["derive"] }
 
@@ -31,35 +31,46 @@ try a declaration in `kuma vm` before a machine you depend on.
 ## Install
 
 Kuma is one self-contained binary: the wallpaper, the greeter config, and
-every desktop asset are compiled into it. Building it needs a Rust
-toolchain at 1.85 or newer and a linker.
+every desktop asset are compiled into it. The published build is static, so
+it needs nothing installed alongside it. This matters on the machines most
+likely to want kuma, which tend to have podman and no compiler.
+
+```console
+$ curl -LO https://github.com/Letdown2491/kuma-linux/releases/latest/download/kuma-x86_64-unknown-linux-musl
+$ chmod +x kuma-x86_64-unknown-linux-musl
+$ sudo mv kuma-x86_64-unknown-linux-musl /usr/local/bin/kuma
+```
+
+Every release is signed. Each one carries the `cosign verify-blob` command
+that checks it came from this repository's release workflow.
+
+The `latest` prerelease is the same binary built from the current `main`,
+for tracking the tree between releases.
+
+Building it yourself needs a Rust toolchain at 1.85 or newer and a linker:
 
 ```console
 $ cargo install --git https://github.com/Letdown2491/kuma-linux --locked
 ```
 
-Or clone it, which also gets you the example declarations and the smoke
-tests:
+Keep `--locked`. Without it cargo ignores the committed `Cargo.lock` and
+resolves dependencies fresh, so you get versions nobody tested.
+
+Cloning also gets you the example declarations and the smoke tests:
 
 ```console
 $ git clone https://github.com/Letdown2491/kuma-linux
 $ cd kuma-linux && cargo install --path .
 ```
 
-Either way the binary is `kuma`.
-
-Keep `--locked` on the first form. Without it cargo ignores the committed
-`Cargo.lock` and resolves dependencies fresh, so you get versions nobody
-tested.
+`kuma --version` reports the commit it was built from, and says `-dirty` if
+that tree had uncommitted changes. Worth checking when a change you just
+made does not show up in the image.
 
 **What needs what.** `init`, `check`, `generate`, and `build` need only
 podman. `switch`, `update`, `rollback`, and `doctor` need to be running on a
 bootc machine. `vm` and `iso` need KVM and sudo.
 
-If you already run an image-based desktop, the obvious place to want this,
-you probably have podman and no compiler. Build kuma in a toolbox or a
-container and copy the binary out.
-
 ## Quick start
 
 ```console
@@ -165,10 +176,9 @@ not obvious from them:
 
 What kuma doesn't do:
 
-- **No published images.** Everything is built locally. An image isn't
-  `bootc switch`-able from anywhere, and nothing is signed yet.
-- **No prebuilt `kuma` binary.** Getting the tool needs a Rust toolchain
-  and a linker.
+- **No published images.** Every image is built locally, so none is
+  `bootc switch`-able from anywhere, and no image is signed. The `kuma`
+  binary is published and signed; the images it builds are not.
 - **No offsite backup.** `[snapshots]` survives a mistake, not a dead
   disk. Blocked on where a repository credential lives, since it cannot be
   the declaration.
 
@@ -0,0 +1,66 @@
+//! Stamps the checkout's identity into the binary.
+//!
+//! `kuma --version` reporting only `0.2.0` would answer the least useful
+//! question. Twice now a change has looked broken because the installed
+//! binary predated it: the niri portal fix appeared not to work, and a
+//! wallpaper swap would have silently baked the old asset. Both times the
+//! binary looked fine and said nothing. The commit it was built from, and
+//! whether the tree was clean at the time, is the thing worth carrying.
+//!
+//! Both values degrade to "unknown" rather than failing the build. A
+//! release tarball has no `.git`, and a build from one is still valid.
+
+use std::path::Path;
+use std::process::Command;
+
+fn main() {
+    // Emitting any rerun-if-changed opts out of cargo's default, which is
+    // to rerun on any file in the package. So the git internals AND the
+    // sources have to be named: HEAD and the ref catch a commit or a
+    // branch switch, the sources catch the edits that make a tree dirty.
+    // Miss the first group and a fresh commit keeps the old sha; miss the
+    // second and "-dirty" outlives the edit that earned it.
+    println!("cargo:rerun-if-changed=.git/HEAD");
+    println!("cargo:rerun-if-changed=.git/index");
+    if let Some(head_ref) = git(&["rev-parse", "--symbolic-full-name", "HEAD"]) {
+        let path = format!(".git/{head_ref}");
+        if Path::new(&path).exists() {
+            println!("cargo:rerun-if-changed={path}");
+        }
+    }
+    for path in ["src", "assets", "Cargo.toml", "Cargo.lock"] {
+        println!("cargo:rerun-if-changed={path}");
+    }
+
+    let sha = match git(&["rev-parse", "--short=7", "HEAD"]) {
+        Some(sha) if dirty() => format!("{sha}-dirty"),
+        Some(sha) => sha,
+        None => "unknown".to_string(),
+    };
+    // The commit's own date, not the build's: two builds of one commit
+    // describe the same code, and saying otherwise invites the belief
+    // that a rebuild changed something.
+    let date = git(&["log", "-1", "--format=%cd", "--date=short"])
+        .unwrap_or_else(|| "unknown".to_string());
+
+    println!("cargo:rustc-env=KUMA_BUILD_SHA={sha}");
+    println!("cargo:rustc-env=KUMA_BUILD_DATE={date}");
+}
+
+/// Trimmed stdout of a successful `git`, or None if git is missing, this
+/// is not a repository, or the command failed.
+fn git(args: &[&str]) -> Option<String> {
+    let out = Command::new("git").args(args).output().ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let text = String::from_utf8(out.stdout).ok()?.trim().to_string();
+    (!text.is_empty()).then_some(text)
+}
+
+/// Whether the working tree has changes the sha does not describe.
+/// Untracked files count: an asset that exists only locally is baked into
+/// the binary exactly like a tracked one.
+fn dirty() -> bool {
+    git(&["status", "--porcelain"]).is_some_and(|s| !s.is_empty())
+}
@@ -430,6 +430,41 @@ mod tests {
         assert!(hashed("hunter2").is_err(), "a plaintext password is not a hash");
     }
 
+    /// The README tells people to download one filename and the release
+    /// workflow publishes another, and nothing else connects the two. A
+    /// rename on either side leaves an install command that 404s, which
+    /// is invisible here and immediate for anyone following the front
+    /// door. So the workflow's asset name is the assertion.
+    ///
+    /// The name is deliberately unversioned, which is what lets the
+    /// README hold a `releases/latest/download/` URL at all; this pins
+    /// that too, since putting the version back would break the link
+    /// silently one release later.
+    #[test]
+    fn the_readme_downloads_what_the_release_workflow_publishes() {
+        let workflow = std::fs::read_to_string(concat!(
+            env!("CARGO_MANIFEST_DIR"),
+            "/.github/workflows/release.yml"
+        ))
+        .unwrap();
+        let target = workflow
+            .lines()
+            .find_map(|l| l.trim().strip_prefix("TARGET: "))
+            .expect("the workflow names a build target");
+        let asset = format!("kuma-{target}");
+        assert!(
+            workflow.contains("echo \"name=kuma-${TARGET}\""),
+            "the workflow builds its asset name from TARGET, unversioned"
+        );
+
+        let readme =
+            std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/README.md")).unwrap();
+        assert!(
+            readme.contains(&format!("releases/latest/download/{asset}")),
+            "README should download {asset} from the latest release"
+        );
+    }
+
     /// The README's example declaration is the first thing anyone copies,
     /// so it is held to the same bar as the committed examples. It has
     /// been wrong before: it showed `password_hash = '...'` for months,
 
@@ -19,8 +19,21 @@ use std::path::{Path, PathBuf};
 pub(crate) const DEFAULT_TAG: &str = "localhost/kuma:latest";
 const BIB_IMAGE: &str = "quay.io/centos-bootc/bootc-image-builder:latest";
 
+/// What `--version` prints. The number alone cannot answer "is this
+/// binary the one that has my last change in it", which is the question
+/// that has actually cost time here. See build.rs for where the stamp
+/// comes from and why a dirty tree is called out.
+const VERSION: &str = concat!(
+    env!("CARGO_PKG_VERSION"),
+    " (",
+    env!("KUMA_BUILD_SHA"),
+    " ",
+    env!("KUMA_BUILD_DATE"),
+    ")"
+);
+
 #[derive(Parser)]
-#[command(name = "kuma", version, about = "Your system is one file.")]
+#[command(name = "kuma", version = VERSION, about = "Your system is one file.")]
 struct Cli {
     /// Path to the kuma config file [default: ./kuma.toml, else
     /// ~/.config/kuma/kuma.toml when the current directory has none]