Get started

Quickstart

Connect a repo and runner, add signing, and start a ReleaseKit workflow.

1. Connect GitHub

Install the ReleaseKit GitHub App on the repository that contains your app. ReleaseKit uses it to read the workflow, list branches, and identify the exact commit sent to your runner.

Return to Projects → New project after installing or changing repository access. If an existing project still references the installation but the workspace connection record is missing, a workspace admin can restore it directly from the New project dialog. If the app is connected but no repositories appear, choose repositories in GitHub and use Refresh repositories.

2. Configure a runner

Under Organization → Runners, register the HTTPS endpoint for your build infrastructure and verify it. The endpoint can dispatch to any cloud, CI system, Buildbarn cluster, or machine.

3. Create a project

In the dashboard, choose the repository, project name, root directory, workflow path, and Production branch. The root directory associates the Release Kit project with one application inside a monorepo; use . when the application lives at the repository root. Assign the organization runner under Project → Runner. Leave Nightly unset until you want a prerelease feed.

4. Add workflow and signing

Add the configured workflow file to the repository with ordered build steps, artifacts, target arches, required environment variable names, and the app-specific signing policy. A root directory selected in the dashboard takes precedence over app.root in the workflow, allowing independent Release Kit projects to share one repository. Entitlement and provisioning files stay versioned with the app. Then create or select an organization Apple signing profile in the dashboard and bind the app to it.

The organization profile owns the Developer ID certificate and notarization credentials. The app policy owns the bundle ID, Hardened Runtime requirement, entitlement paths, and optional provisioning profile. A runner can therefore build several apps without storing any app secret permanently.

5. Install the CLI

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

login opens the dashboard, authenticates with the same WorkOS account, and lets you choose the active project.

6. Create a candidate

Open the repository-aware terminal dashboard:

release-kit

The dashboard detects the current GitHub repository, selects the matching ReleaseKit project, and offers the safe next actions. You can also create candidates directly:

Use Preview while developing:

release-kit preview

Publish Nightly or Production when you want a promotable candidate:

release-kit publish nightly
release-kit publish production

The CLI asks for a patch, minor, or major bump when needed. You can also pass --patch, --minor, or --major. By default, Production and Nightly update the app version file, commit that bump, push it, and create the candidate from the pushed commit. If release-kit.yml declares app.version, the repository resolver validates and returns the version instead; Release Kit does not create a version commit or reinterpret repository-specific prerelease naming. Nightly versions start from the current Nightly baseline. Approving a Production release does not change the Nightly feed; publish and promote Nightly separately when Early Access users should move.

7. Promote

Open the build link printed by the CLI. When checks pass, approve Production to update the stable feed, or approve Nightly to update the nightly feed with a prerelease.

Preview never updates a feed.