Releasing the desktop app
How to sign a Mac build by hand, and how a tagged release builds every platform and reaches installed apps. Building
and running the app from a checkout is in its README; installing and using it is
The desktop app. Paths to scripts/ and src-tauri/ below are under apps/desktop/.
A signed build on a Mac
pnpm --filter @andon/desktop build:localAPPLE_SIGNING_IDENTITY="Developer ID Application: …" ANDON_NOTARY_PROFILE=<profile> pnpm --filter @andon/desktop release:macscripts/release-mac.mjs signs every binary the local server carries (Node with src-tauri/node.entitlements, Postgres,
the agent’s node-pty, whose sums in board/agent/latest.json and board/install.sh it rewrites), has Tauri build and sign the app
(with src-tauri/app.entitlements, the microphone for dictation and voice; src-tauri/Info.plist adds the reasons macOS shows for the microphone and, for dictation, speech recognition), then
notarises and staples the app and a .dmg under src-tauri/target/release/bundle/dmg/, named with the version and
the commit it was built from (Andon_0.1.0-abcde_arm64.dmg). The profile is an App Store
Connect API key saved once with xcrun notarytool store-credentials <profile> --key AuthKey_….p8 --key-id … --issuer …;
--no-notarize stops after signing, and --dmg-only makes only the .dmg again from the last run’s app.
The .dmg opens on src-tauri/dmg/background-2x.png: the octopus in its tank, with the app and Applications either
side of a bubble arrow (positions in release-mac.mjs, DMG_ICONS). scripts/dmg-background.mjs --style <picture>
makes candidates for a new one with a Gemini image model (GEMINI_API_KEY, and GEMINI_REFERER for a
referrer-restricted key, from .env.local); the picture is a look to match, such as the website’s hero.
Release every platform
.github/workflows/desktop.yml builds every platform, each on its own runner:
- macOS Apple silicon, signed and notarised by
release-mac.mjs - Windows x64
- Linux x64 and arm64
To release, bump the version in package.json, src-tauri/tauri.conf.json and src-tauri/Cargo.toml (all three
must agree), commit the matching src-tauri/Cargo.lock change, merge, then push a tag desktop-v<version>. The workflow checks the tag against the version, builds,
and publishes to the public store or bucket:
desktop/<version>/: the installers,SHA256SUMSand that release’slatest.json.desktop/latest.json: what installed apps read for updates. It is uploaded last, so it never points at a file that isn’t there yet.
On Blob, the release’s files are cached for a year and desktop/latest.json for a minute (Blob’s least), so
installed apps see a release within about a minute.
A version is published once; a second publish of it is refused. Every merge into main also builds every platform,
without publishing (a newer merge cancels an older one’s build), so a broken build shows before the release. Other
branches don’t build: running the workflow by hand works on main only, and only builds unless you tick “publish”.
What it reads. The secrets belong to two environments (Settings → Environments), each limited to the main branch
and desktop-v* tags under “Deployment branches and tags”, so no other branch’s workflow can read them: the Apple and
updater secrets to desktop-signing, which the builds run in, and the publishing ones to desktop-release, which the
publish job runs in. The variables are the repository’s (Settings → Secrets and variables → Actions). Each secret
reaches only the steps that sign or publish with it, never pnpm install or the tests.
| Name | Kind | What |
|---|---|---|
APPLE_CERTIFICATE_P12, APPLE_CERTIFICATE_PASSWORD |
desktop-signing secret |
The “Developer ID Application” certificate with its private key, exported from Keychain Access as a .p12 and base64-encoded, and its export password. |
APPLE_API_KEY_P8, APPLE_API_KEY_ID, APPLE_API_ISSUER_ID |
desktop-signing secret |
An App Store Connect API key for notarising (App Store Connect → Users and Access → Integrations → Team Keys, “Developer” access): the downloaded AuthKey_….p8 base64-encoded, its key ID, and the issuer ID shown above the list. |
TAURI_SIGNING_PRIVATE_KEY, TAURI_SIGNING_PRIVATE_KEY_PASSWORD |
desktop-signing secret |
The key updates are signed with: pnpm --filter @andon/desktop tauri signer generate -w andon-updater.key. Keep a copy offline: losing it means installed apps can’t update. |
DESKTOP_UPDATER_PUBKEY |
variable | The matching andon-updater.key.pub, which the app checks updates against. |
BLOB_READ_WRITE_TOKEN |
desktop-release secret |
To publish to a Vercel Blob store: the token of a public store (Vercel → Storage → the store → .env.local). When it is set, the S3 settings below aren’t needed or used. |
DESKTOP_S3_ACCESS_KEY_ID, DESKTOP_S3_SECRET_ACCESS_KEY |
desktop-release secret |
Or, to publish to an S3 bucket: write access to it. |
DESKTOP_S3_BUCKET, DESKTOP_S3_ENDPOINT, DESKTOP_S3_REGION |
variable | The bucket, its S3 endpoint (empty for AWS; Cloudflare R2’s is https://<account>.r2.cloudflarestorage.com) and region (auto for R2). |
DESKTOP_PUBLIC_URL |
variable | The https address the files are served at publicly: a Blob store’s own (https://<store>.public.blob.vercel-storage.com, which publishing checks), or the bucket’s, such as a custom domain. |
desktop-release can also require an approval before anything is published. A build without the Apple
secrets is unsigned. A build without the updater key and variables has no updater, which is also true of every local
build.
In the app: a release build checks desktop/latest.json at launch and every six hours. It downloads a newer
version in the background, then shows a notification and Andon › “Restart to Update to …”. Nothing installs until
you choose that. Andon › “Check for Updates…” checks at once.
The local Andon runs from inside the app, so it is stopped before the new version goes in and started again by the
updated app. On Linux only the AppImage updates itself; a .deb or .rpm install is updated by installing the new
package.
An update made by hand (a new .dmg’s app dragged over the old one, an installer, a new package) can go in while the
local Andon runs, and the local Andon keeps running when the app quits, so it would go on serving the old board with
the old server and agent. Each build:local writes a build-id into the bundle, and andon up records the build it
started the server from in ~/.andon/server.build. At launch the app compares the two and restarts a local Andon an
older build started (one started before builds were recorded is recognised by its server.mjs command line; one
started from a checkout is left alone), so the board, the server and the agent are this version’s.
Release the agent
Andon’s official agent releases are what install.sh pins by default and what a machine updates from when its own
board serves no signed build (Agent updates; the design is
official agent releases). They live in the same public store or bucket
as the app, under agent/, in a board’s own layout: agent/latest.json, agent/andon-<version>.mjs and
agent/prebuilds/<os>-<arch>/<file>.
OFFICIAL_AGENT_RELEASE in packages/shared/src/update-manifest.ts names the store’s address (DESKTOP_PUBLIC_URL)
and the release key’s public half. While either is empty, there is no official channel.
To release, raise AGENT_VERSION in apps/agent/src/version.ts, merge, then push a tag agent-v<version>.
.github/workflows/agent-release.yml runs the agent tests, builds the board, checks every file against its
latest.json and the tag (scripts/agent-release.mjs check), signs latest.json (sign), then publishes: the
bundle, cached for a year, then the native files and latest.json, with a minute’s cache. A version is published once.
Machines take only a release newer than the agent they run, so every release needs a higher version.
It runs in a third environment, agent-release, limited to agent-v* tags, with the publishing secrets above and:
| Name | Kind | What |
|---|---|---|
ANDON_UPDATE_SIGNING_KEY |
agent-release secret |
Andon’s release key: an Ed25519 private key, PKCS#8 DER, base64url-encoded. Its public half (SPKI DER, base64url) must be OFFICIAL_AGENT_RELEASE.key, or signing stops. Keep a copy offline: losing it means machines can’t take new official releases until they pin a new key. |
