buzz/RELEASING.md

Releasing Sprout Desktop

This document describes how to create a new OSS release of the Sprout desktop app.

---

Prerequisites

• Write access to the block/sprout GitHub repository. Only collaborators with push permissions can trigger the release workflow.
• The following GitHub Actions secrets must be configured on the repo (Settings > Secrets and variables > Actions):

  Secret	Purpose
  SPROUT_UPDATER_PUBLIC_KEY	Tauri updater public key (minisign)
  TAURI_SIGNING_PRIVATE_KEY	Tauri updater private key (used to sign the update archive)
  TAURI_SIGNING_PRIVATE_KEY_PASSWORD	Password for the private key

---

Creating a Release

1. Go to Actions > Release in the GitHub UI:
   https://github.com/block/sprout/actions/workflows/release.yml

2. Click "Run workflow".

3. Fill in the inputs:

   • version — a semver version string, e.g. 0.4.0 or 1.0.0-beta.1. Do not include a v prefix.
   • ref — the branch, tag, or commit SHA to build from. Defaults to main.

4. Click "Run workflow" to start the build.

The workflow will:

• Validate the version string
• Check out the specified ref
• Patch the version into package.json, tauri.conf.json, and Cargo.toml
• Build all sidecar binaries (sprout-acp, sprout-mcp, git-credential-nostr)
• Build the Tauri desktop app with updater signing enabled
• Create a versioned GitHub release (v0.4.0) with the .dmg installer
• Update the rolling sprout-desktop-latest release with the signed update archive and latest.json manifest for the auto-updater

---

What Gets Published

Each release produces two GitHub releases:

1. v<version> (e.g. v0.4.0) — the user-facing release with the .dmg installer. This is what users download manually.

2. sprout-desktop-latest — a rolling pre-release used by the Tauri auto-updater. Contains latest.json, the signed .tar.gz archive, and its .sig signature. Users should not download from this release directly.

---

Platform Support

The release workflow currently builds for macOS ARM64 only (darwin-aarch64). Intel Mac (darwin-x86_64) support would require adding a matrix build to the workflow.

Code Signing (macOS)

OSS release builds use ad-hoc code signing (signingIdentity: "-") rather than a Developer ID certificate. This means the app is not notarized by Apple.

On first launch, macOS Gatekeeper will block the app with a "damaged" or "unidentified developer" message. Users can bypass this by right-clicking the app > Open (or via System Settings > Privacy & Security). After the first launch the app will open normally.

---

Auto-Updater

The desktop app checks for updates by fetching latest.json from the sprout-desktop-latest release:

https://github.com/block/sprout/releases/download/sprout-desktop-latest/latest.json

When a new version is available, the app downloads the signed archive, verifies the signature against the embedded public key, and applies the update.

---

Troubleshooting

Build fails at "Validate version"

The version string must be valid semver: MAJOR.MINOR.PATCH with an optional pre-release suffix (e.g. 1.0.0-beta.1). Do not include a v prefix.

Build fails at "Build Tauri app"

Check that the signing secrets are configured correctly. The build requires TAURI_SIGNING_PRIVATE_KEY and TAURI_SIGNING_PRIVATE_KEY_PASSWORD to be set.

Auto-updater reports "no update available"

Verify that the sprout-desktop-latest release exists and contains a valid latest.json. If the user is on Intel Mac, no update will be found (ARM64 only).