Guide

Instant rollback

How ReleaseKit rolls desktop apps back to the last known-good release.

Instant rollback changes the active updater feed back to a previously published release. It does not rebuild, resign, or reupload the app during the incident.

Rollback is designed for the stressful moment when a promoted desktop release is bad and the fastest safe action is to stop serving it.

What Happens

When you confirm a rollback, ReleaseKit performs one operation with two effects:

1. It promotes the target release manifest back into the active channel feed.
2. It marks the recalled release as blocked in update policy.

For a Stable rollback, the active stable feed starts serving the previous known-good release again. Clients that have not installed the recalled version simply stop seeing it. Clients already on the recalled version receive a forced update policy that allows the updater integration to downgrade to the rollback target.

Why Feed Promotion Matters

The updater installs the version described by the channel manifest, such as latest-mac.yml. The policy response tells the app which feed to check, but the feed manifest decides which artifact is downloaded.

That means rollback must update both:

If policy changes without feed promotion, the dashboard may say the release was recalled while the app still reads the bad channel manifest.

Artifact Layout

New production and staging releases are uploaded to both mutable channel paths and immutable release paths.

my-app/stable/latest-mac.yml
my-app/stable/releases/1.2.3/latest-mac.yml
my-app/stable/MyApp-1.2.3-arm64.dmg
my-app/stable/releases/1.2.3/MyApp-1.2.3-arm64.dmg

The mutable channel path is what installed apps check. The immutable release path is what rollback uses as the source of truth when promoting an older manifest back into the channel feed.

Updater Behavior

Apps using a ReleaseKit updater integration do not need a separate rollback control plane.

For clients already on a recalled release, ReleaseKit returns a forced update response with downgrade enabled:

{
  "status": "forced-update",
  "version": "1.2.3",
  "blockedVersion": true,
  "allowDowngrade": true,
  "downgradeBlocked": false
}

The updater integration applies allowDowngrade before checking the feed. Normal non-rollback downgrades remain blocked. Framework adapters, including Electron-based apps, own the platform-specific updater wiring.

Preconditions

A rollback target must:

• be in the same app, channel, platform, and architecture as the recalled release
• be older than the recalled release
• not be blocked
• include a valid updater manifest artifact
• have a manifest that ReleaseKit can promote into the active channel feed

For releases published before immutable release paths existed, rollback may require a manual backfill. Copy the desired release manifest and artifacts into the expected releases/<version> paths before relying on instant rollback.

Operational Flow

1. Open the ReleaseKit dashboard.
2. Review the current Production release.
3. Choose Instant Rollback.
4. Confirm the target version and affected install count.
5. ReleaseKit promotes the target manifest, blocks the recalled release, and records rollback metadata.
6. Watch the affected version cohort in PostHog until installs move off the recalled version.

If feed promotion fails, ReleaseKit fails the rollback before saving policy state. That keeps the dashboard and updater feed from disagreeing.

Testing Rollback

Use staging before relying on rollback in production:

1. Publish version 1.2.3.
2. Publish version 1.2.4.
3. Confirm the active feed serves 1.2.4.
4. Roll back to 1.2.3.
5. Confirm the active feed manifest now contains 1.2.3.
6. Check an app installed on 1.2.4.
7. Confirm policy returns forced-update with allowDowngrade: true.
8. Download and install the update.
9. Confirm the app launches on 1.2.3.

Also test a client on a newer non-blocked version. It should not downgrade unless that installed version is blocked or explicitly targeted by policy.