Release

Releases are built and published by CI on the public repo (NicholasFlemmer/styx-app), never from a laptop.

1. Bump version in apps/desktop/package.json (every release needs a new number; the feed refuses a version it already serves) and land it. mirror.yml pushes it to styx-app's sync branch; sync-pr.yml opens a pull request that merges itself once CI passes (about 35 minutes). Wait for that merge before step 2.
2. Start the release: gh workflow run release.yml -R NicholasFlemmer/styx-app -f version=X.Y.Z (or push a vX.Y.Z tag to styx-app). verify checks the version, waits for CI on that exact commit to pass, and tags it. Mac (signed + notarized, retried on network errors), Windows and Linux build in parallel; draft attaches every installer and feed file to a draft release.
3. Review the draft on styx-app › Releases. Only the owner presses Publish release: that is the gate.
4. Publishing runs publish.yml: the update feed (installers first, feed files last, keyless upload through Workload Identity), a check that all three feeds serve the new version, then the Homebrew cask bump in NicholasFlemmer/homebrew-styx. When it succeeds, site.yml rebuilds and redeploys heystyx.com so its stated version matches (run it by hand after a site-only change).
5. Check: curl -s https://storage.googleapis.com/styx-desktop-releases/mac/latest-mac.yml | head -1, and an installed copy shows "Update available" within 30 minutes.

If a step fails, fix the cause, bump nothing, and re-run the failed jobs (a draft can be deleted and release.yml re-run for the same version until it is published).

Local builds (debugging only)

pnpm release:preflight, then pnpm package:mac (notarizes with the styx-notary keychain profile) or pnpm -F @styx/desktop package:mac:dir && pnpm -F @styx/desktop package:smoke for an unsigned check. pnpm release:publish still uploads a local release/ folder through the gcloud shim, for emergencies only.

Packaging notes (learned 2026-09-05)

• Only native modules (better-sqlite3, node-pty, @napi-rs/keyring, ssh2) stay external in electron.vite.config.ts; every other main-process dependency is bundled. A packaged app that require()s ESM-only packages (execa, chokidar) at runtime hangs before app.whenReady.
• apps/desktop/package.json declares packageManager: pnpm@… so electron-builder resolves the hoisted workspace node_modules; workspace packages are devDependencies (bundled by electron-vite), which keeps Storybook/Jest out of the bundle.
• Without a signing identity electron-builder ad-hoc signs; never pass CSC_IDENTITY_AUTO_DISCOVERY=false on Apple Silicon (an unsigned bundle inherits a broken Electron signature).
• Windows installers are named Styx-Setup-<version>.exe (no spaces: GitHub renames spaces in release assets).