Guides
View as MarkdownProgressive 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 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 for your language: only the URL changes.
// 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)")!// 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"// 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:
$ 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:
hotcfg rollout mobile-flags --env production --percent 504. 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.
hotcfg rollout mobile-flags --env production --complete
hotcfg rollout mobile-flags --env production --abortEach 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-Versionon 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=Nor?bucket=0, and on a public bin that means anyone with the URL. A private bin 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
ETagand304: 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
rolloutevent when one starts, changes share, completes or is aborted, and the audit log records each step. See Webhooks. - 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.
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 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.
Last updated 17 November 2026