# 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](https://github.com/psci-labs/andon/blob/main/apps/desktop/README.md); installing and using it is
[The desktop app](https://andon-docs.pages.dev/guide/desktop-app.md). Paths to `scripts/` and `src-tauri/` below are under `apps/desktop/`.

## A signed build on a Mac

```
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](https://andon-docs.pages.dev/machines/updates.md); the design is
[official agent releases](https://github.com/psci-labs/andon/blob/main/docs/internal/specs/official-agent-releases.md)). 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. |
