Release Runbook

Also available: Markdown · Plain text

Release Runbook — Gnomad Desktop Assistant

Audience: Maintainers cutting alpha/beta releases
Last updated: June 2026

Overview

Releases are tag-driven. Pushing a v* tag (or using workflow dispatch) runs .github/workflows/release.yml, builds installers for all platforms, and attaches them to a GitHub Release.

Platform Artifacts
macOS Universal .dmg
Linux x86_64 .deb, .rpm, .AppImage
Linux ARM64 .deb, .AppImage
Windows .msi, NSIS .exe

In-app updates require signed artifacts — see UPDATER.md.

Pre-release checklist

  1. Version bump — align package.json, src-tauri/tauri.conf.json, and src/lib/brand.ts (if applicable).
  2. CHANGELOG — move [Unreleased] items under the new version heading.
  3. Docs — npm run docs:export after any doc edits; verify GitHub Pages links.
  4. Local QA — npm run test, cd src-tauri && cargo test, npm run build.
  5. Manual smoke (see QA_CHECKLIST.md):
    • Cloud + local chat
    • Agent shell + fs tools
    • Sudo Gate / Path Gate tokens
    • Settings → Updates (check only; full install needs signed release)
  6. Updater keys — run npm run verify:updater (must pass before tagging); set CI secrets TAURI_SIGNING_PRIVATE_KEY and TAURI_SIGNING_PRIVATE_KEY_PASSWORD — see UPDATER.md.

Cut a release

1. Merge to main

All release work should be on main (or the branch your workflows watch).

2. Create and push a tag

git tag -a v0.2.0-beta.1 -m "Gnomad v0.2.0-beta.1"
git push origin v0.2.0-beta.1

Or use Actions → Release → Run workflow with a tag name (creates/updates the release for that tag).

3. Monitor CI

Open the Release workflow run. Expect four matrix jobs:

Each job uploads assets via tauri-action with includeUpdaterJson: true.

4. Verify GitHub Release

5. Post-release verification

Check How
macOS install Open DMG, drag to Applications, launch
Linux x86_64 sudo dpkg -i gnomad_*.deb or run AppImage
Linux ARM64 Same on ARM board / VM
Windows Run MSI or setup.exe
Updater Install previous build → Settings → Updates → Install (requires valid signing keys)

Document results in QA_CHECKLIST.md or a release issue.

Hotfix workflow

  1. Branch from the release tag or main.
  2. Fix + tests + CHANGELOG entry.
  3. Merge to main.
  4. Tag patch version (v0.2.0-beta.2).

Do not force-push tags that users may already have installed.

Rollback

GitHub Releases cannot be “un-published” cleanly for users who already downloaded. For a bad build:

  1. Mark the release as pre-release or add a prominent warning in release notes.
  2. Publish a new patch tag with the fix.
  3. If updater keys were compromised, rotate minisign keys and update pubkey in tauri.conf.json (users on old builds will not auto-update until they install manually once).

CI secrets reference

Secret Required for Notes
GITHUB_TOKEN All releases Provided by Actions
TAURI_SIGNING_PRIVATE_KEY Signed updates Minisign private key contents
TAURI_SIGNING_PRIVATE_KEY_PASSWORD Signed updates Empty string if no password

Built with ❤️ by Gnomad Studio 🦙