Guides

# Progressive rollouts

Give a new version of your config to a share of your users first, raise the share as it proves itself, then give it to everyone or take it back.

A rollout gives a new version to some of an environment's readers first: 5% of your apps, then 25%, then everyone. If something goes wrong, only that share saw it, and aborting takes it back within about a minute.

## How it works

hotcfg never knows who your users are, so each app says which share it's in. It picks a **bucket**, a number from 0 to 99, once, keeps it, and sends it with every read as `?bucket=`. While a rollout runs at 20%, apps in buckets 0 to 19 get the new version, and everyone else keeps the current one.

Because an app keeps its bucket, raising the share only adds apps: at 50%, buckets 0 to 49 get it, including the 0 to 19 that already had it. Nobody flips back and forth.

Apps that send no bucket always get the current version. That includes the [fetching code](https://hotcfg.run/docs/guides/fetching) as it is, so a rollout only reaches apps you've changed to send one.

## 1. Send a bucket from your app

Pick the bucket at random the first time, store it, and add it to the URL. Use it with the [fetching code](https://hotcfg.run/docs/guides/fetching) for your language: only the URL changes.

**Swift:**

Swift

```
// Picked once per install and kept, so the app stays in its share.
let defaults = UserDefaults.standard
if defaults.object(forKey: "hotcfg.bucket") == nil {
    defaults.set(Int.random(in: 0...99), forKey: "hotcfg.bucket")
}
let bucket = defaults.integer(forKey: "hotcfg.bucket")
let url = URL(string: "https://api.hotcfg.run/v1/acme/mobile-flags?bucket=\(bucket)")!
```

**Kotlin:**

Kotlin

```
// Picked once per install and kept, so the app stays in its share.
val prefs = context.getSharedPreferences("hotcfg", Context.MODE_PRIVATE)
val bucket = prefs.getInt("bucket", -1).takeIf { it >= 0 }
    ?: (0..99).random().also { prefs.edit().putInt("bucket", it).apply() }
val url = "https://api.hotcfg.run/v1/acme/mobile-flags?bucket=$bucket"
```

**JavaScript:**

JavaScript

```
// Picked once per browser and kept, so the user stays in their share.
let bucket = localStorage.getItem("hotcfg-bucket");
if (bucket === null) {
  bucket = String(Math.floor(Math.random() * 100));
  localStorage.setItem("hotcfg-bucket", bucket);
}
const URL = `https://api.hotcfg.run/v1/acme/mobile-flags?bucket=${bucket}`;
```

Send the number as it is: `?bucket=7`, not `07`, which is refused with `400 invalid_bucket`. For another environment, add it after `env`: `?env=staging&bucket=7`.

In other languages, do the same: a random integer from 0 to 99, saved wherever the app keeps its settings. To keep a user in the same share across their devices, derive the bucket from a stable id you already have instead, such as the remainder of a hash of their account id divided by 100.

A server is one reader: give each instance a bucket the same way if your servers should take part, or send none to keep them on the current version.

## 2. Start the rollout

A rollout starts with a promote, so what reaches users is exactly what you checked in staging. In the dashboard, open the bin, press **Promote…**, choose staging → production, tick **Roll out gradually** and enter the share. Or with the [CLI](https://hotcfg.run/docs/cli/rollout):

terminal

```
$ hotcfg promote mobile-flags --from staging --to production --percent 10
✓ Rolling out mobile-flags staging v14 → production v13 to 10%
  others   v12, and apps that send no ?bucket=
```

The copy is checked against the schema like any promote, and becomes a new version in production's history. Production's current version doesn't change.

## 3. Raise the share

Watch what you'd watch after any release: crash reports, errors, support. Then raise the share on the bin's **Payload** tab, which shows the rollout while it runs, or with:

terminal

```
hotcfg rollout mobile-flags --env production --percent 50
```

## 4. Complete or abort

**Complete** gives the new version to everyone, with or without a bucket: it becomes production's current version. **Abort** gives everyone the current version again; the new version stays in history.

terminal

```
hotcfg rollout mobile-flags --env production --complete
hotcfg rollout mobile-flags --env production --abort
```

Each change purges the environment's edge cache, every bucket included, as soon as it's made. Apps get it on their next fetch, or up to a minute later if their HTTP cache still holds a copy: reads may be kept for 60 seconds (`max-age=60`).

## What to know

- **One rollout per environment, and it holds the environment.** While it runs, publishing, promoting or rolling back into that environment is refused with `409 rollout_in_progress`. Complete or abort it first. Unpublishing the environment ends it.
- **The schema covers both versions.** A schema change must accept the rollout's version as well as the current one.
- **Reads report what they got.** `X-Hotcfg-Version` on each response says which version the app was served. A `?v=` read gets that exact version, rollout or not.
- **A rollout is not access control.** The share decides which version an app gets by default, not who can read the new one. Any reader can ask for it with `?v=N` or `?bucket=0`, and on a public bin that means anyone with the URL. A [private bin](https://hotcfg.run/docs/reference/reading#private-bins) keeps it from people without a key, but the publishable key ships inside your app, where it can be extracted. Leave anything that must stay secret, such as an unannounced feature's name, out of config apps read.
- **Caching still works.** Each bucket is cached at the edge on its own, with its own `ETag` and `304`: at most 100 copies per environment. A `?query=` filter sent with a bucket makes 100 copies of that filter, so keep the filters few.
- **Your team hears about it.** Webhooks send a `rollout` event when one starts, changes share, completes or is aborted, and the [audit log](https://hotcfg.run/docs/account/audit-log) records each step. See [Webhooks](https://hotcfg.run/docs/guides/webhooks#what-your-endpoint-gets).
- **Who can do it.** The same people who can promote into the environment: in production, administrators and the owner, or a secret key allowed to write it.
- **It moves when you move it.** There's no automatic schedule and no automatic abort: hotcfg can't see your crash rates.
- **Rollouts are part of Pro.** On Free, starting one or changing its share is refused with `403 rollouts_require_pro`. If the organization moves to Free while a rollout runs, it's aborted: every app gets the current version again within about a minute, and the new version stays in history. See [Billing](https://hotcfg.run/docs/account/billing#moving-to-free).

## Rollouts and overrides

A rollout ships a whole new version to a share of readers, for a while. To keep different values for some readers for good, such as old builds or one platform, use [overrides with a jq filter](https://hotcfg.run/docs/recipes/version-targeting) in the config itself.

## API

| Request | Does |
| --- | --- |
| `POST /v1/{org}/{bin}/promote` with `{"from_env": "staging", "to_env": "production", "percent": 10}` | Starts a rollout. The response's `rollout` has the new `version`, the `percent` and the `current_version` everyone else gets. |
| `POST /v1/{org}/{bin}/rollout` with `{"env": "production", "percent": 50}` | Changes the share, from 1 to 99. |
| `POST /v1/{org}/{bin}/rollout/complete` with `{"env": "production"}` | Gives the new version to everyone. |
| `POST /v1/{org}/{bin}/rollout/abort` with `{"env": "production"}` | Gives everyone the current version again. |
| `GET /v1/{org}/{bin}?bucket=37` | Reads as an app in bucket 37. |

A running rollout also shows in each bin's `environments`, as `rollout: {"version", "percent", "current_version", "started_at"}`. Changing, completing or aborting when none runs answers `409 no_rollout`; starting one in an environment that serves nothing answers `409 nothing_to_roll_out_from`. See the [API reference](https://hotcfg.run/docs/reference/api).

Last updated 17 November 2026
