How updates flow through Minnow — releasing a new version (for maintainers) and receiving one (for users). Auto-update is built on electron-updater against GitHub Releases (henrigrimm/minnow). Implementation: electron/updater.ts + electron/updater-core.ts; UI in src/ui/settings-updates.ts and src/os/update-menubar.ts. Tracked in MIN-384.

Platform support today: Windows (NSIS), Linux (AppImage), and signed macOS (Developer ID + notarization). Unsigned macOS installs show a disabled updater with a signing note. On Windows/macOS hosts, build Linux with npm run package:linux:docker (Docker). Dev and browser sessions can't self-update and show a hint instead of controls.

Open Actions → version release → Run workflow:

1. Select the branch to release (normally main).
2. Enter a stable version such as 0.1.7 or v0.1.7, newer than every existing stable tag.
3. Leave Publish immediately unchecked to create a draft for review, or check it to publish as the Latest Stable release after all builds and verification pass.
4. Run the workflow. Its summary links to the completed release.

The workflow builds Windows NSIS, Linux AppImage, and signed Apple Silicon macOS DMG/ZIP packages using the same commands and macOS secrets as the nightly beta workflow below. Every job checks out the same commit. The entered version is applied to package.json and the lockfile in the build workspace; the workflow does not commit a version bump back to the source branch. To keep source builds aligned, also bump and commit the version with npm version 0.1.7 --no-git-tag-version.

Before creating a release, it requires all three update feeds and their installers, and checks the version, sizes, and SHA-512 hashes. Assets upload to a draft first. An upload failure leaves that draft unpublished. Existing releases (including drafts) and stable tags cannot be overwritten; delete an incomplete draft before starting a fresh run for the same version. Use Re-run failed jobs to retry a failed package job before a draft has been created. For a completed draft, review the notes and publish it as Latest on GitHub when ready.

Release notes come from documentation/releases/v<version>.md when present; otherwise GitHub generates notes. Drafts remain invisible to the in-app updater.

You can also start it with the GitHub CLI:

# Build a draft for review
gh workflow run version-release.yml --ref main -f version=0.1.7 -f publish=false

# Build and publish directly to Stable
gh workflow run version-release.yml --ref main -f version=0.1.7 -f publish=true

The workflow must be present on the default branch before GitHub enables manual runs.

Local packaging never uploads anything (electron-builder runs with --publish never). You can also create a versioned GitHub release by hand. The build.publish config in package.json exists only so packaging emits the latest.yml feed file. Four steps:

Edit version in package.json:

{
  "version": "1.0.1"   // was 1.0.0
}

This is mandatory for every release. An installed app decides whether to update by comparing its own version against the one in latest.yml. If you don't bump, nobody upgrades. Use semver: patch for fixes, minor for features.

npm run package

This runs build → electron:build → headless:build → electron-builder and writes to release/pkg/:

On https://github.com/henrigrimm/minnow/releases → Draft a new release:

• Tag: v<version> (e.g. v1.0.1), created against the commit you packaged from.
• Attach platform artifacts from release/pkg/ (Windows) and release/pkg-linux/ when you built Linux via Docker. At minimum per platform: installer/binary + matching feed (latest.yml on Windows, latest-linux.yml on Linux) + .blockmap where electron-builder emits one. Without the feed file, installed apps never see the release.
• The feed and the installer must be from the same build. electron-updater hashes the downloaded .exe / AppImage / zip against sha512 + size in the YAML. Replacing an installer on an existing tag without replacing that platform’s latest*.yml looks like “it downloaded but will not install.” After attaching assets, run node scripts/verify-github-update-feed.mjs.
• Publish the release (do not leave it as a draft). Draft releases are invisible to electron-updater; Settings will show Could not check for updates until the release is published.
• Release notes / body: this text is what users see under "What's new" in Settings and in the menubar popover. Write it for users, not as a changelog dump.

The pre-release checkbox on the GitHub release is the channel switch:

Beta rides GitHub pre-releases via autoUpdater.allowPrerelease — there's no separate beta feed to maintain.

beta nightly release runs every day at 03:30 UTC (and can be run manually). It packages Windows, Linux, and Apple Silicon macOS from main. It uses the package version when it is ahead of the latest stable tag; otherwise it advances to the next patch, then appends a unique -beta.YYYYMMDD.RUN.ATTEMPT suffix, and publishes it as a GitHub pre-release only after every installer and update feed has uploaded. Users on the Beta channel receive it through the existing updater; Stable users do not.

Before enabling its macOS job, add these repository Actions secrets:

The macOS job intentionally fails when these are absent: unsigned macOS builds disable the in-app updater and are not suitable for the beta release channel.

[ ] Bumped version in package.json (and committed)
[ ] npm run package:win (and package:linux or package:linux:docker) succeeded
[ ] release/pkg/ has .exe + latest.yml + .blockmap; Linux AppImage + latest-linux.yml if shipping Linux
[ ] GitHub release tagged v<version>
[ ] All platform feed files and installers attached
[ ] Release notes written for users
[ ] Pre-release flag set correctly (unchecked = Stable, checked = Beta)

Builds are unsigned, so the first manual install of the .exe may trigger a SmartScreen warning ("More info → Run anyway"). Auto-updates after that first install are silent — the user doesn't re-clear SmartScreen on every update.

Automatic and calm by design. On a packaged Windows install:

1. Check. 15 seconds after launch, then every 4 hours, the app fetches latest.yml and compares versions. Launch is never blocked on this.
2. Download. A newer version downloads in the background automatically — no prompt, no interruption.
3. Install on your terms. Click Restart to update when you're ready. If you never do, the update installs automatically the next time you quit Minnow normally.

Menubar pill (left of the settings gear) — silent unless there's something to act on:

Settings → General → App updates — the full picture and all manual controls:

• Status strip: up to date / checking / downloading % / ready / couldn't check.
• Installed version, Last checked, Next automatic check.
• Update channel: Stable / Beta toggle.
• Check for updates button (manual check).
• Restart to update button (appears when a build is ready).
• What's new expander with the release notes.

Toggle Stable ↔ Beta in Settings → General → App updates. No reinstall — the choice persists to ~/.minnow/updater.json and triggers an immediate re-check. Beta simply opts you into GitHub pre-releases, which may be less stable; switch back anytime.

Deliberately quiet:

• Background check fails (offline, GitHub unreachable) → silent, logged, retried next cycle. No toasts.
• You click "Check for updates" and it fails → an inline error in the status strip (the only place failures surface, since you asked).
• A download is interrupted → retried on the next cycle; a build that already finished downloading stays "ready" and is never lost to a later failed check.

The complete "old install upgrades itself" path can only be exercised once two versions exist on GitHub Releases. The practical first validation:

1. Release 1.0.1, install it.
2. Release 1.0.2.
3. Launch the 1.0.1 install and confirm it detects 1.0.2, downloads, shows the menubar pill, and installs on restart.

Unit coverage for the state machine and UI lives in test/electron/updater-core.test.mts, test/settings/settings-updates.test.mts, and test/os/update-menubar.test.mts.