Skip to content
AndonDocs
GitHub
Change Andon

Releasing the desktop app

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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

text
pnpm --filter @andon/desktop build:local
APPLE_SIGNING_IDENTITY="Developer ID Application: …" ANDON_NOTARY_PROFILE=<profile> pnpm --filter @andon/desktop release:mac

scripts/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, SHA256SUMS and that release’s latest.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.