docs/RELEASING.md

Releasing — self-updating builds for mac / linux / windows

This doc covers the release workflow after the auto-updater wiring landed. Read top-to-bottom the first time. After that, cutting a release is the three commands in §5.

1. One-time repo setup

The signing key was generated locally at ~/.tauri/omnivoice-updater.key (private) and ~/.tauri/omnivoice-updater.key.pub (public). The public key is already embedded in frontend/src-tauri/tauri.conf.json — that's what shipping clients use to verify updates.

The private key needs to live in GitHub Actions Secrets so CI can sign each release:

1. Read the private key contents:

   cat ~/.tauri/omnivoice-updater.key
   

2. GitHub → Settings → Secrets and variables → Actions → New repository secret (on debpalash/OmniVoice-Studio, which is where the updater endpoint points):
   • Name: TAURI_SIGNING_PRIVATE_KEY
   • Value: paste the full contents (including the untrusted comment: header line)
3. Add a second secret:
   • Name: TAURI_SIGNING_PRIVATE_KEY_PASSWORD
   • Value: leave blank (the key was generated without a password)

Back the key up. Copy ~/.tauri/omnivoice-updater.key to a password manager or encrypted vault. If you lose it, you can never ship an update for any client that has the current public key — they'll be stranded and need a manual reinstall.

2. One-time account setup (you)

Rotate the leaked GH token (the ghp_... in origin remote). See the session transcript — already flagged. Do this before anything else.

No Apple Developer / Windows signing certs needed for v1. Apps ship unsigned; first-launch shows "unverified developer" warnings that users bypass with right-click → Open (mac) or "Run anyway" (Windows SmartScreen). Self-update still works — Tauri's updater verifies via its own signing key, independent of OS code signing.

3. What the updater does

On every app launch, the webview:

1. Fetches https://github.com/debpalash/OmniVoice-Studio/releases/latest/download/latest.json
2. Compares the version in latest.json to the running app's version (from tauri.conf.json)
3. If newer, shows a native dialog: "A new version (x.y.z) is available. Download and install now?"
4. If user accepts, downloads the signed update bundle, verifies the minisign signature against the embedded pubkey, replaces the app in place, relaunches.

Failures (no network, 404, signature mismatch) are silent — the app continues to launch normally. Check the frontend devtools console for Updater check failed messages if you're debugging.

4. Version bumps

Two files must agree before you tag a release:

• frontend/src-tauri/tauri.conf.json → "version": "0.2.0"
• frontend/src-tauri/Cargo.toml → version = "0.2.0"

(Not frontend/package.json — Tauri ignores it.)

Keep bumps monotonic. Tauri updater uses semver comparison, so v0.2.0 does not update clients already on v0.2.1.

5. Cutting a release

# 1. Bump versions in the two files above, commit.
git add frontend/src-tauri/tauri.conf.json frontend/src-tauri/Cargo.toml
git commit -m "release: v0.2.0"

# 2. Tag and push.
git tag v0.2.0
git push origin main
git push origin v0.2.0

The Desktop Release workflow fires on tag push. It builds four targets in parallel on GitHub Actions runners:

Target	Runner	Artifact
macOS Apple Silicon	macos-14	.dmg + updater .app.tar.gz
macOS Intel	macos-13	.dmg + updater .app.tar.gz
Windows x64	windows-2022	.msi + .exe + updater .nsis.zip
Linux x64	ubuntu-22.04	.AppImage + .deb + updater .AppImage.tar.gz

Each runner signs the updater payload with the stored TAURI_SIGNING_PRIVATE_KEY, merges into a single latest.json, and attaches everything to the draft release.

Workflow runtime: ~20-40 minutes (PyInstaller + four platform builds). Follow progress at: https://github.com/debpalash/OmniVoice-Studio/actions

When it finishes, the draft release needs manual publishing — GitHub → Releases → Edit the draft → Publish release. Once published, existing clients detect the update on their next launch.

6. Expect-to-fail-first-time on Windows and Linux

mac-ARM is tested locally. The other three platforms will likely hit PyInstaller issues on their first CI run because neither dependency set nor platform quirks have been exercised. Common failures to expect:

• Windows: mlx_whisper is mac-only — need to conditional-guard the import in backend.spec. demucs's CUDA autodetect may pull wheels we don't want. Long-path limits during the PyInstaller bundle.
• Linux: libasound / libwebkit2gtk dev headers vs runtime confusion. AppImage FUSE assumptions on the runner.
• mac-Intel: should work, but torch wheels for x86_64 differ — watch for nvidia-* wheels sneaking in via the default torch.

When a target fails, either fix the root cause in the spec / workflow, or comment that matrix row out temporarily and keep the working targets shipping. The fail-fast: false setting means one failure doesn't kill the others.

7. Testing the updater locally (before shipping a tag)

Two options:

Option A — dry run the manifest: After a release is published, hit the updater URL manually:

curl -L https://github.com/debpalash/OmniVoice-Studio/releases/latest/download/latest.json | jq

You should see platform-keyed download URLs + minisign signatures. If that JSON looks right, clients will pick it up.

Option B — full end-to-end:

1. Install v0.1.0 on a fresh machine (or clean-installed Applications).
2. Cut v0.2.0 (bump, tag, push, wait for CI, publish draft).
3. Launch the installed v0.1.0. Within seconds, the dialog should appear.
4. Accept → app downloads, verifies, replaces, relaunches as v0.2.0.

If step 3 silently does nothing, DevTools console in the app webview has the Updater check failed: log.

8. Rolling back

There's no "revert update" flow for clients — they'll only see a newer version. To roll back:

1. Delete the broken release from GitHub Releases (or mark it as pre-release).
2. Re-tag the previous good commit with a higher version (e.g., if you shipped bad v0.2.0, tag v0.2.1 on the old v0.1.0 commit).
3. Clients auto-update to the "new" v0.2.1 which is actually the old code.

Ugly but it works. Better plan: test with Option B above before publishing the draft.