Guide

Desktop app setup

What the app still needs to own.

Your app repository should stay boring: source code, package metadata, build commands, and runtime update checks.

Your configured runner owns build execution. ReleaseKit owns workflow scheduling, signing secret storage, artifacts, feeds, approvals, and rollback.

App Responsibilities

Area	What to keep in the app
Source	Desktop app code and package metadata
Builds	`release-kit.yml` with ordered build steps, artifacts, targets, and required env names
Updates	Use the ReleaseKit app integration to check for promoted releases
UI	Show update availability, download, install, and restart states
Telemetry	Send product and updater analytics directly to PostHog

ReleaseKit Responsibilities

Area	What ReleaseKit owns
Workflows	Parse the DAG, queue ready jobs, issue scoped leases, and record results
Runners	Sign job submissions to the organization endpoint selected by the project
Secrets	Apple signing and app build secrets in the vault
Lanes	Production, Nightly, and Preview policy
Releases	Artifacts, feeds, approvals, promotion, and rollback

Production approval only publishes to the Stable channel. Nightly is its own feed; Early Access users move only when you publish and promote a Nightly candidate.

Do not hand-wire runner endpoints or release-control APIs into the shipped app. Runner selection is dashboard-only; the app should only know how to ask ReleaseKit whether an update is available.

Workflow

Put project jobs in release-kit.yml. Release Kit expands the dependency graph and matrices, snapshots the parsed workflow onto each candidate, and sends ready jobs to the project’s configured runner.

By default, Release Kit selects Production and Nightly versions and commits them to app.versionFiles. Repositories with their own stable naming scheme can instead declare app.version.run. The command must validate repository-specific rules, exit nonzero for an invalid release, and print exactly one semantic version. Release Kit records that returned version without applying its built-in final/prerelease lane naming rules.

app:
  root: .
  versionFiles:
    - npm/package.json
  version:
    run: node .release-kit/scripts/version.mjs
    timeoutMinutes: 5

release-kit.yml

schemaVersion: 2
app:
root: sol
versionFiles:
  - package.json
  - sol/package.json
runtime:
node: "22"
pnpm: "10.24.0"
env:
required:
  - MAIN_VITE_WORKOS_CLIENT_ID
  - MAIN_VITE_INSPECTOR_API_BASE_URL
  - MAIN_VITE_TCC_API_KEY
jobs:
build:
  trigger: candidate
  matrix:
    platform: [darwin]
    arch: [arm64, x64]
  steps:
    - name: Install
      run: pnpm install --frozen-lockfile
    - name: Build macOS artifacts
      cwd: sol
      timeoutMinutes: 45
      run: pnpm run build && pnpm exec electron-builder --mac --${RELEASE_KIT_ARCH} --publish never
  artifacts:
    - sol/dist/*.dmg
    - sol/dist/*.zip
    - sol/dist/*.yml

Apple Signing Credentials

Apple signing setup has one dashboard-guided path:

Open the Apple signing setup in the ReleaseKit dashboard.
Download the one-time setup credentials.
Run npx -y @sandbox-technologies/release-kit@latest apple setup on your Mac.
Follow the terminal while it creates the certificate request, opens Apple Developer, validates the returned .cer, and uploads encrypted credentials.

ReleaseKit keeps the matching private key in the vault and leases signing material only to the scoped workflow job running on your configured runner.

Build Environment Variables

Add project-specific environment variables in the ReleaseKit project Environment variables page. The runner leases only the values required by that workflow job. Keep public build-time configuration in the repository when it is not secret, and declare required secret names under env.required so missing configuration fails before execution.

Start

preview

npm install -g @sandbox-technologies/release-kit
release-kit login
release-kit preview

When you are ready to ship, run:

production

release-kit publish production

Production and Nightly wait for approval before feeds change. Preview is artifact-only.

For incident response details, see Instant rollback.