# Staged Rollouts — Bundle Drop Docs

> Roll out OTA updates gradually with Bundle Drop staged rollouts and sticky per-install cohorts.

Canonical: https://bundledrop.app/docs/staged-rollouts

## What a Staged Rollout Is

A staged rollout lets you release a bundle gradually instead of sending it to everyone on a channel at once.

For example, you might start with 10%, watch for issues, then increase to 25%, 50%, and finally 100%.

For staged rollout to work on a channel, that channel must have [Managed Publishing](/docs/managed-publishing) enabled. Managed publishing is the gate that makes rollout eligibility matter.

This read-only example expands bundle v42 in `production`, with an optional `plan = pro` audience rule. The same sample installs keep their buckets throughout the ramp. Highlighting means eligible on the next update check, not already installed.

## Why Teams Use It

Staged rollouts are useful when you want to:

- reduce risk on production channels
- test a release with a smaller audience first
- expand a rollout step by step while monitoring results

Even within a rollout, each device is still protected by [automatic recovery](/docs/automatic-recovery), which restores a healthy fallback after repeated incomplete OTA startups.

## How It Works

At a high level:

1. Before uploading, enable [Managed Publishing](/docs/managed-publishing) for the channel.
2. Upload the bundle to that channel.
3. In the dashboard, you start or update a staged rollout for that bundle.
4. Bundle Drop gradually makes that bundle eligible for more installs on that same channel.
5. When you are confident, you move the rollout to 100%.

The app does not need special code for this beyond normal Bundle Drop integration. The rollout is controlled from the dashboard.

Enable managed publishing before uploading a release you want to hold for rollout. If it is disabled, a new compatible upload can already become eligible before you create a rollout.

In the dashboard, staged rollout is configured from a channel's Bundles page for the bundle you want to release.

## How Devices Are Chosen

Each install is assigned to a stable bucket derived from its install ID. When you set a rollout to 25%, installs in buckets below 25 are eligible — not a fresh random draw on every check. This selects roughly a quarter of the audience; actual counts vary.

Because the bucket is deterministic per install, cohorts are **sticky** as you ramp:

- moving from 10% to 25% to 100% only *adds* new installs to the rollout
- a device that already qualified stays in the rollout at every higher percentage
- you never reshuffle or pull an update back from devices that already received it

This makes staged rollouts safe to increase gradually: you are always expanding the audience, never churning it.

The bucket is derived from the install ID alone, so it is stable across every rollout in the project — the same low-bucket installs are consistently in the earliest slice of each rollout, rather than being re-drawn independently per release.

## Related Controls

Staged rollout works with these related controls:

- [Managed Publishing](/docs/managed-publishing) is required. Without it, staged rollout is not the mechanism deciding bundle eligibility on that channel.
- [Targeted Rollout](/docs/targeted-rollout-properties) is optional. It adds an audience filter before the rollout percentage is applied.

## What the Client Needs to Know

Most client teams only need to remember three things:

- staged rollout happens per channel
- managed publishing must be enabled for staged rollout to be effective
- targeted rollout is optional and only narrows the audience further

## Related Docs

- For release tracks, see [Channels](/docs/channels).
- For channel-level eligibility control, see [Managed Publishing](/docs/managed-publishing).
- For audience targeting, see [Targeted Rollout](/docs/targeted-rollout-properties).
- For reverting a bad release, see [Rollback](/docs/rollback).
- For publishing bundles, see [Uploading](/docs/uploading).