════════════════════════════════════════════════════════════════════════
  RELEASE RUNBOOK
  Gnomad Desktop Assistant · docs/RELEASE_RUNBOOK.md
════════════════════════════════════════════════════════════════════════

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

  [bash]
    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:

  • macos-latest — universal DMG
  • ubuntu-22.04 — Linux x86_64 deb/rpm/AppImage
  • ubuntu-24.04-arm — Linux ARM64 deb/AppImage
  • windows-latest — MSI + NSIS

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

4. Verify GitHub Release

  • Assets named gnomad-[name]-[version]-[platform][ext]
  • latest.json present (updater manifest)
  • Release notes readable; mark pre-release for alpha/beta

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  

────────────────────────────────────────

RELATED DOCS
------------

  • UPDATER.md — key generation and channels
  • BUILD_PLATFORMS.md — local build commands
  • LINUX_PACKAGES.md — install and ARM64 notes
  • QA_CHECKLIST.md — sign-off matrix

────────────────────────────────────────

Built with ❤️ by Gnomad Studio 🦙

════════════════════════════════════════════════════════════════════════
Built with ❤️ by Gnomad Studio 🦙
https://gnomadstudio.org
════════════════════════════════════════════════════════════════════════