Desktop auto-update (Electron, GitHub Releases)

The Electron app keeps itself current by polling GitHub Releases on launch and applying updates automatically when the user opts in.

How it works

1. You tag a new version (e.g. git tag v0.4.0 && git push origin v0.4.0).
2. .github/workflows/release.yml runs on tag push. The electron matrix job runs on macos-latest / windows-latest / ubuntu-latest, each calling npx electron-builder --publish always.
3. electron-builder uploads the per-OS installer + a manifest file to the GitHub Release for that tag:
   • macOS: Mark It Down-X.Y.Z-arm64.dmg, …-x64.dmg, …-arm64-mac.zip, …-x64-mac.zip, latest-mac.yml, …blockmap
   • Windows: Mark It Down Setup X.Y.Z.exe, latest.yml
   • Linux: Mark It Down-X.Y.Z.AppImage, mark-it-down_X.Y.Z_amd64.deb, latest-linux.yml
4. Running clients (apps/electron/main.ts → setupAutoUpdate()) fire autoUpdater.checkForUpdatesAndNotify() on launch. electron-updater fetches latest-mac.yml / latest.yml / latest-linux.yml, compares the version, downloads the matching artifact in the background.
5. The user is prompted twice:
   • When the new version is detected → an info dialog ("Downloading in the background…").
   • When the download finishes → a choice dialog: Install on next launch or Restart and install now.

What ships in the bundle

The publish block in package.json#build is wired to GitHub:

electron-updater reads the same block at runtime to know where to look. No separate URL or feed config.

Channels

process.env.MID_CHANNEL (or the matching VSCode setting) drives the channel:

MID_CHANNEL	Behavior
unset / latest	Stable channel — only non-prerelease tags are offered
beta	Pre-release tags (e.g. v0.4.0-rc.1) are also offered

The release workflow's release-notes step automatically marks any tag with a hyphen (v0.4.0-rc.1) as a GitHub pre-release, so the stable channel skips it.

What doesn't auto-update

• Dev builds (MID_DEV=1 or non-packaged) skip the entire flow — setupAutoUpdate() returns early with a console log.
• Unsigned macOS builds can install fresh but can't apply updates — Apple Gatekeeper rejects the differential update on unsigned apps. See docs/desktop-mac-signing.md to wire signing.

Failure modes

Symptom in console	Cause	Fix
checkForUpdatesAndNotify failed: Cannot find latest-mac.yml	The release was published before the manifest was uploaded, OR the OS didn't run electron-builder for this tag	Re-run the failed CI job
code signature verification failed on macOS update	Update was signed with a different identity than the running app	Don't rotate Developer ID mid-version. If you must, ship a fresh DMG and have users reinstall
Auto-update dialog never appears	setupAutoUpdate() early-returns in dev (intentional). In packaged builds, check the GitHub Release exists and isn't marked prerelease	Confirm the release page shows the assets

Manual check

In the running app: Help → Check for Updates triggers autoUpdater.checkForUpdates() directly without waiting for the launch poll.

Where to look in the code

• apps/electron/main.ts — setupAutoUpdate() (event wiring), broadcastUpdateState() (sync to renderer for the status bar), the Help → Check for Updates menu item.
• package.json#build.publish — the GitHub provider config.
• .github/workflows/release.yml — the CI pipeline that builds + uploads.
• docs/auto-update.md — covers the full picture across both surfaces (extension + desktop) including channel detection.
• docs/releasing.md — runbook for cutting a release.