Release Policy

This runbook describes how to prevent users on stale desktop installers from completing OAuth (including Gmail), when the canonical flow is the latest release.

Distribution

• GitHub Releases is the primary source for desktop builds
• Tauri updater endpoint should direct users to current release artifacts
• Retire stale stable artifacts: when abandoning a release line, delete or hide stale installer assets, update website/CDN download links, refresh the updater manifest

OAuth Minimum App Version

The production web build embeds the minimum supported app semver at build time, so the OAuth deep link cannot complete on deprecated binaries.

Variable	Purpose
VITE_MINIMUM_SUPPORTED_APP_VERSION	Desktop app must be ≥ this version to complete openhuman://oauth/success
VITE_LATEST_APP_DOWNLOAD_URL	Optional; defaults to GitHub latest release. Opened when gate blocks OAuth

Workflow: Staging vs. Production

Two first-class GitHub Actions workflows, selected by intent rather than a toggle flag:

Workflow	Branch	Upgrade	Push Tag	Concurrency Group
release-staging.yml	main	patch only	v<version>-staging	release-staging
release-production.yml	main	patch/minor/major	v<version>	release-production

Cutting a Staging Build

1. Run Release (Staging) from main via workflow_dispatch
2. Workflow bumps patch on main, commits chore(staging): vX.Y.Z, pushes branch, and creates an immutable vX.Y.Z-staging tag at that commit
3. Build matrix runs from tag (not main HEAD), so reruns rebuild identical bytes

Promoting to Production

1. Run Release Production from main via workflow_dispatch, with release_source = staging_tag
2. Workflow strips -staging, creates v<version> at the same commit, and runs production build matrix from that tag

Hotfixes

1. Run Release Production with release_source = main_head
2. Workflow runs legacy upgrade and tagging path on main

Tag Strategy and Rollback

• Naming. Staging tags use SemVer pre-release suffix -staging, so they sort before matching production tags
• Collision. Both workflows fail fast when the target tag already exists
• Rollback (production). Failed build matrix triggers cleanup-failed-release, which deletes the draft GitHub Release and v<version> tag
• Rollback (staging). Failed staging build deletes the v<version>-staging tag

Release Checklist

1. Bump app/package.json and app/src-tauri/tauri.conf.json
2. Set VITE_MINIMUM_SUPPORTED_APP_VERSION to the new floor
3. Delete, redirect, or retire old stable installers and stale updater entries
4. Smoke test Gmail connect from a fresh install at releases/latest
5. Complete the manual smoke checklist, then paste it into the release PR description

Next Steps

• Testing Strategy - Testing tiers
• E2E Testing - End-to-end tests