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 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.

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)")!

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:

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 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 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

RequestDoes
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=37Reads 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