openswarm/docs/RELEASE_RUNBOOK.md

Release Runbook

How an OpenSwarm desktop release is built, verified, and promoted. The guiding rule: a release is reproducible and provenanced — anyone can tell exactly what commit produced a given DMG/EXE, and rebuilding that commit yields the same bits. Distribution stays on GitHub Releases (auto-updater feeds live there).

Versioning

Source of truth is electron/package.json version. Bump it only when cutting a release (see CONTRIBUTING.md for semver rules). A - suffix (e.g. 1.2.0-beta.1) marks an experimental/pre-release build; the Windows CI and the build scripts set the pre-release channel automatically from that suffix.

What is pinned (reproducibility)

Thing	Pin	Where
uv	0.11.16	scripts/build-app.sh, scripts/build-app-win.ps1 (override UV_VERSION)
Node (bundled runtime + CI toolchain)	20.18.1	build scripts, .nvmrc, .github/workflows/*
9router	0.3.60	scripts/fetch-router.{sh,ps1} (override ROUTER_VERSION)
Python	3.13.2 standalone	scripts/build-python-env*.{sh,ps1}
Python deps	fully hash-locked	backend/requirements.lock
npm deps	lockfile-exact via npm ci	frontend/package-lock.json, electron/package-lock.json
electron-builder + deps	exact (no ^)	electron/package.json

Both package-lock.json files are committed — npm ci refuses to run without them. Do not re-add them to .gitignore.

Regenerating the Python lock

After editing backend/requirements.txt:

uv pip compile backend/requirements.txt --python-version 3.13 \
    --generate-hashes --output-file backend/requirements.lock

Commit both files together. Verify with a clean 3.13 env: install from the lock, uv pip check, and import anthropic / pydantic / httpx / trafilatura / claude_agent_sdk / uvicorn.

Provenance

Every build writes electron/build-info.json (gitignored, regenerated) with the git rev-parse HEAD sha, build time, channel, and version. It ships in the asar and surfaces in two places:

• Startup log line in backend.log: [provenance] OpenSwarm <ver> sha=<short> channel=<...>
• Settings → General → Advanced → About → Build

To confirm an artifact's provenance: launch it, open Settings, and compare the Build sha to git rev-parse HEAD of the tag you released.

Build (local)

• macOS: bash scripts/build-app.sh (unsigned) / --sign / --publish. Needs APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID for signing.
• Windows: pwsh scripts/build-app-win.ps1 (unsigned) / -Sign / -Publish. Signing is Azure Trusted Signing; CI handles it (see below).

Release (CI)

Pushing a v* tag triggers .github/workflows/release-windows.yml, which builds

• signs the Windows installer and uploads it to the GitHub Release for that tag. macOS currently publishes from a Mac via bash publish.sh.

Recommended order so neither platform's users skip a version:

1. macOS: bash publish.sh (produces latest-mac.yml).
2. Windows: push the v* tag (or pwsh publish-win.ps1), producing latest.yml.
3. Verify both latest.yml and latest-mac.yml exist on the release and their versions match before the release leaves draft.

Tag protection (immutable releases)

Release tags must never move once cut — a moved tag silently re-points the auto-updater feed at different bits. Configure a GitHub ruleset to enforce this (Settings → Rules → Rulesets → New ruleset):

1. Target: Tags, pattern v*.
2. Enable Restrict creations off, Restrict updates on, Restrict deletions on. (Equivalently: block non-fast-forward / force-push and deletion on the refs/tags/v* ref.)
3. Apply to all users (no bypass list, or restrict bypass to break-glass only).

Verify: push a throwaway tag, then git push --force origin <tag> to move it → GitHub must reject it. Delete the throwaway afterward (allowed only if you temporarily exempt it, or use a non-v* name for the test).

GitHub releases are also independently markable immutable; tag protection is the load-bearing control because the auto-updater resolves the tag, not the release.