Releasing Gravity

A release is an annotated v* tag on main; use the configured signing identity for official tags. Pushing that tag runs .github/workflows/release.yml. It builds the desktop app on GitHub-hosted macOS ARM64 and Windows x64 runners in parallel, packages gravityd, and a final job creates the GitHub release once both builds pass. Signing, notarization and updater artifacts are configurable; see docs/public-builds.md for the required variables and secrets. Verify that configuration before releasing. For an existing distribution, preserve the updater signing pair. When changing download endpoints, retain a compatibility bridge for every endpoint embedded in existing installations. Publishing latest.json makes configured running apps offer the update. Verify the intended repository and existing publication authorization before pushing a tag; do not infer access to official signing credentials in a contributor fork.

The rule that governs everything here

The version lives in six files and the workflow refuses to build unless they all agree with the tag. The Resolve version step compares the tag name (minus v) against Cargo.toml, apps/desktop/src-tauri/Cargo.toml, apps/desktop/package.json and apps/desktop/src-tauri/tauri.conf.json; the two Cargo.lock files must follow or the build dirties them. The desktop crate sits outside the root workspace, so nothing propagates a version for you.

1. Pick the version

Look at what landed since the last tag — that is the whole changelog:

git fetch origin --tags
git describe --tags --abbrev=0 origin/main
# Use that tag as <previous-tag>; if no tag exists, review origin/main in full.
git log <previous-tag>..origin/main --oneline

Pre-1.0, so: minor for anything user-visible — a new feature, a removed feature, a removed or renamed config key, a changed default. Patch only for fixes and internals nobody can observe. State the reasoning in the bump commit; that message is the release's rationale.

2. Land the bump PR

Never bump straight on main — it goes through a PR like any other change with a What/Why/How tested description.

git switch -c release/vX.Y.Z origin/main
# edit the four manifests, then sync both lockfiles:
cargo update --workspace --offline
(cd apps/desktop/src-tauri && cargo update --workspace --offline)

apps/desktop/pnpm-lock.yaml also contains a 0.11.0 — that is the @xterm/addon-web-links dependency, not ours. Leave it.

Commit as chore(release): bump version to X.Y.Z, open the PR against main with the usual What/Why/How tested body and link the primary GitHub issue (#123). Before pushing, run pnpm run verify (typecheck, tests, lint, builds and visual checks). Regenerate dependency notices with pnpm notices:generate when versions or lockfiles change; follow third-party/README.md for the pinned toolchain. Wait for all required PR checks, including visual and secret scanning. Ask before merging unless the user already said to — merging is what makes the tag possible.

3. Tag the merge commit

Create an annotated tag; use your configured signing identity if tag signing is enabled:

git fetch origin
git tag -a -m "Gravity X.Y.Z" vX.Y.Z <merge-commit-sha>
git push origin vX.Y.Z

Tag the actual merged commit on origin/main, not local HEAD, and re-check the manifests in that commit first:

git show <sha>:Cargo.toml
git show <sha>:apps/desktop/src-tauri/Cargo.toml
git show <sha>:apps/desktop/package.json
git show <sha>:apps/desktop/src-tauri/tauri.conf.json

A pushed tag uploads all assets to a draft GitHub release, then publishes it as latest. Existing R2 objects remain available, but new releases do not upload there.

4. Watch the run

gh run list --workflow release.yml --limit 3
gh run watch <run-id> --exit-status --interval 30

Build and notarization times vary. gh run watch may stop on a transient HTTP 404 from the jobs API — that says nothing about the run. Fall back to polling in the background rather than assuming failure:

for i in $(seq 1 60); do
  s=$(gh run view <run-id> --json status,conclusion -q '.status+" "+.conclusion')
  case "$s" in completed*) echo "$s"; break;; esac
  sleep 30
done

Notarize DMG is the long step — Apple's service, not the runner.

5. Verify the publish, don't trust the green check

gh release view vX.Y.Z --json name,url,assets
# Fetch the updater endpoint configured for this distribution, if enabled.

Expect the DMG, the Windows x64-setup.exe and the gravityd tarball. With updater signing enabled, also expect .app.tar.gz, the .sig for it and for the Windows installer, and latest.json with darwin-aarch64 and windows-x86_64 entries. Fetch the configured manifest and confirm its version and GitHub artifact URL. Check the legacy manifest bridge and website download redirect too, and verify updater signatures against the existing public key. Keep the bridge for dormant installations.

Also check the release notes: the workflow appends a Gatekeeper/xattr warning when notarization was unavailable. That is expected for builds without Apple credentials; official notarized distributions should treat it as a failure.

Dry runs

workflow_dispatch on release.yml builds from tauri.conf.json's version and only uploads artifacts to the run — no tag or GitHub release. Use it to prove a build change before tagging.

When a release goes wrong

Recovery is normally forward: fix, bump to the next patch, and tag again. Do not delete or move a published tag or replace its signed archives — apps may already have the manifest. If a bad release is latest, select the previous verified GitHub release as latest to stop new clients discovering it. Point the legacy bridge at that same version-specific manifest if needed. This stops future update offers; it does not downgrade installed apps.

See apps/marketing/README.md for the bridge activation and rollback procedure. Do not remove the old R2 custom domain or historical artifacts during recovery.