Percentage-Based Rollouts
A percentage rollout offers a patch to a share of the devices on its track, such
as 10% of the devices on stable. Raise the share as you gain confidence in the
patch, up to 100%. If the patch misbehaves, roll it back. Shorebird picks the
devices when they check for patches, so your app needs no extra code.
Before you start
Section titled “Before you start”- Rollouts need Shorebird 1.6.139 or newer. Run
shorebird upgradeto get it. - Only releases built with Flutter 3.35.7 or newer take part. Devices on a release built with an older Flutter are outside every rollout below 100%; they get the patch once it reaches 100%. See How devices are chosen.
- Rollouts work on every plan.
Start a rollout
Section titled “Start a rollout”Pass --rollout with the percentage when you publish the patch:
Without --rollout, a patch goes to every device on its track. Run
shorebird patch --help for the values --rollout accepts.
shorebird patches promote and shorebird patches set-track take --rollout
too. Moving a patch onto a track starts a new rollout there, so you can test a
patch on staging and then promote it to 10% of stable:
Moving a patch to another track with Change track in the Shorebird Console puts it on that track at 100%. The Console doesn’t set or show rollout percentages; use the CLI or the API.
shorebird patches list and shorebird patches info show a patch that’s
partway through its rollout next to its track, such as stable (10%).
Raise a rollout
Section titled “Raise a rollout”Raise it to 100 to offer the patch to every device on its track. You need the same permission as for moving the patch onto its track.
A rollout only goes up: shorebird patches rollout refuses a lower percentage.
Devices that got the patch keep getting it as you raise the percentage. For a
patch that’s already on its track, use shorebird patches rollout, not
promote.
When you patch several platforms at once, such as
shorebird patch --platforms=android,ios, each platform’s patch gets its own
number and its own rollout. shorebird patch prints the
shorebird patches rollout command for each; raise each one by its number.
Stop a rollout
Section titled “Stop a rollout”The CLI can’t lower a rollout. Leaving the percentage where it is holds the rollout at that share: devices outside it keep getting what they had, the newest patch on the track that’s at 100%. To stop serving the patch at all, roll it back.
If the patch is broken, roll it back. Devices that
installed it remove it on their next check. The Rolling out card in
Mission Control doesn’t look at rollout percentages: a stable patch at 10%
can show there, with its Roll back button, like any other. See
Roll back from the rollout card
for which patch the card shows.
How devices are chosen
Section titled “How devices are chosen”Each install of your app has an anonymous install identifier, which the updater sends with each patch check. Shorebird hashes it with the patch to put the install at a fixed position from 0 to 100%. A patch at 10% is offered to the installs whose position is below 10%.
- The position doesn’t change, so an install in the rollout stays in it as you raise the percentage.
- Each patch has its own positions. An install in the first 10% of one patch’s rollout may be outside the next patch’s.
- The identifier is per install. Uninstalling the app or clearing its data gives the next install a new identifier, and so a new position.
- An install outside a rollout gets the newest patch for its platform on its track that’s at 100%, or no patch if there isn’t one. When several patches are rolling out on the same track, an install gets the newest one it’s in.
- A rollout reaches no one if its patch is numbered below a patch for the same platform that’s at 100% on the same track, since the newer patch outranks it.
- Releases built with a Flutter version older than 3.35.7 send no identifier, so their devices are outside every rollout below 100%.
The percentage is of the installs that check that track, so 10% on stable is
10% of the devices on stable, not of every device.
Watch the rollout
Section titled “Watch the rollout”To see what share of devices run the patch, run:
It shows, for each patch, the share of the release’s devices running that patch or a later one. It needs Shorebird 1.6.129 or newer; see Metrics commands.
In the Shorebird Console, when the Rolling
out card at the top of Mission Control shows your patch, it counts the
devices running that patch or a later one, out of the release’s devices on the
patch’s platform, not only the ones in the rollout. The count needs a release
built with Flutter 3.47.4 or newer, since older releases don’t report which
patch a device is running. On an older release the card says Rollout adoption
needs Flutter 3.47.4+ instead. The card moves on to a newer patch or release,
and shrinks to a Last shipped line a week after the patch was created or
once 80% of those devices have it (when the card shows the count); see
Roll back from the rollout card.
To follow a longer rollout, use shorebird metrics adoption.
For a patch’s downloads and installs, open the release and go to its Insights tab. Patch activity charts each patch’s downloads and installs over time, and All-time installs totals the installs per patch. These count download and install events, so a device that reinstalls the app counts again; they aren’t a count of devices.
Protected tracks and deployment freezes
Section titled “Protected tracks and deployment freezes”On a protected track, each step of a rollout
needs approval. Publishing or promoting a patch to the track with --rollout
files an approval request at that percentage. shorebird patches rollout is
refused there: to raise the percentage, promote the patch to the track again at
the new percentage, which files a new request. The CLI refuses to promote a
patch to the track it’s already on, so send that request with
shorebird api. It
answers 409 with patch_approval_required and a link to the request, which
means the request was filed; running it again replaces that request:
PATCH_ID and CHANNEL_ID are IDs, not the patch number or the track’s name.
shorebird patches info prints a patch’s ID, and
shorebird api /apps/APP_ID/channels lists the tracks’ IDs.
During a deployment freeze,
putting any patch on stable and raising a rollout on it are refused unless you
override the freeze.
From the API
Section titled “From the API”Raise a rollout with
PUT /apps/{appId}/releases/{releaseId}/patches/{patchId}/rollout and a body
such as {"rollout_percentage": 50}. The promote endpoint,
POST /apps/{appId}/patches/promote, takes rollout_percentage too. The
rollout endpoint is marked unstable in the spec, since its shape may change.
List release IDs with shorebird api /apps/APP_ID/releases, and see the
API reference.
On Enterprise, both endpoints also take a timed schedule in rollout_steps: 2
to 10 rising percentages ending at 100, each step but the last with a
duration_minutes to hold before the next. Shorebird raises the rollout at each
step, and can pause over weekends with rollout_pause_weekends and
rollout_timezone.
Choose the devices in your app instead
Section titled “Choose the devices in your app instead”You can also run a rollout yourself, by choosing a track in your app’s code.
This helps when you need to reach releases built with a Flutter version older
than 3.35.7, or to lower a rollout, which the CLI can’t do. Otherwise, use
--rollout.
The sample code for this approach is at https://github.com/shorebirdtech/samples/tree/main/progressive_rollout_demo
It has three parts:
- Using Shorebird’s “tracks” feature to publish patches to different sets of users.
- Using a cloud key-value (KV) store to manage rollout percentages for each release version.
- Randomly assigning every device a “group number” between 1 and 100. If a device’s group number is less than or equal to the current rollout percentage for the current app version, that user will get the partially rolled-out (“beta”) patch. Otherwise, the user will receive the stable patch.
Add Shorebird to your app
Section titled “Add Shorebird to your app”If you haven’t already, run Shorebird init in your Flutter project to add Shorebird to your app.
Add the shorebird_code_push package
Section titled “Add the shorebird_code_push package”This feature also requires v2.0.0 of
package:shorebird_code_push.
You can add this to your project using flutter pub add shorebird_code_push or
by adding it to your pubspec.yaml manually.
You will need to update your shorebird.yaml to tell Shorebird you want to
manage your own updates (see
auto_update):
Add logic to bucket your users
Section titled “Add logic to bucket your users”Do this by assigning each user a number between 1 and 100 and saving that value
to a local cache using
package:shared_preferences:
Add logic to determine rollout percentage
Section titled “Add logic to determine rollout percentage”This guide uses Firebase’s Cloud Firestore to create a simple key-value pairing of release versions to rollout percentages, although any method of retrieving a rollout percentage from the cloud will work.
Use these values to choose a track
Section titled “Use these values to choose a track”Now, tie this all together by using the group number and the rollout percentage to decide whether a user should get patches in the beta track or in the stable track.
Check for patches on that track
Section titled “Check for patches on that track”Pass the track to both checkForUpdate and update:
_updater is a ShorebirdUpdater(). The sample app calls _checkForUpdate()
from a button. In your app, call it each time the app starts, without awaiting
it, so the device keeps checking the track its group belongs to. With
auto_update: false, this call is also how devices learn that a patch was
rolled back, so make it early in startup; see
Update strategies. update() throws an
UpdateException when the update fails; see
When update() throws.
Seeing it in action
Section titled “Seeing it in action”So that the patch is easy to spot, first change the seedColor in main.dart
from Colors.deepPurple to Colors.red. Then create a release for Android:
This will create a release build of your app (an aab file) that is patchable with Shorebird. You will distribute this build to your users the same way you distribute your apps today.
Now, launch the example using shorebird preview, which downloads the release
and runs it on a local device:

This screenshot shows that the device is in group 76. This means that it will request patches on the stable track until the rollout percentage is >= 76, at which point it will start requesting patches in the beta track.
Because a patch hasn’t been created on the beta track or a rollout percentage set yet, there isn’t much to see yet.
Change the seedColor back to Colors.deepPurple and create a patch on the
beta track using the following command:
And update the rollout percentage in Firebase:

Press the update button, and the Shorebird preview output shows the following (formatted for readability):
Now, change the rollout percentage in Firebase to 76%:

Press the update button again, and you’ll now see:
Note that the channel field in the patch check request has changed from stable to beta, and that the patch has been downloaded.

Finish the rollout
Section titled “Finish the rollout”Once the patch has reached 100% and you’re happy with it, promote it to
stable:
Devices checking stable now get it, including new installs. Promoting moves
the patch off beta, and a device that asks for a track with no patch keeps the
patch it has, so devices that already run it keep running it. Then remove the
release’s rollout percentage, so every device checks stable again. For how
promotion works, see
Promoting a patch between tracks.
The Rolling out card in Mission Control doesn’t show a patch while it’s
on beta. Once it’s on stable, the card can show it with a count of devices
updated; see
Roll back from the rollout card
for which rollout the card shows. The card’s week counts from when the patch was
created, so a patch that spent more than a week on beta shows only as a Last
shipped line.
Stop the rollout
Section titled “Stop the rollout”To stop more devices getting the patch, set the release’s rollout percentage
to 0. Devices then check stable again. What a device that already installed
the patch runs after that is covered in
Switching a device between tracks.
If the patch is broken, roll it back as well. A rollback applies to the patch on every track, so devices that installed it remove it on their next check, whichever track they ask for.