Tracks

Tracks are named deployment channels that control which devices receive a patch. Every Shorebird app has a built-in stable track, which is the default channel that all devices subscribe to. You can create additional tracks on the fly, simply by naming them when publishing a patch. No configuration or registration is needed; a track is created the first time you publish to it. To create, list, or delete tracks yourself, see Managing tracks from the CLI.

Note

The CLI calls tracks channels in some places, such as the shorebird channels commands. Track and channel mean the same thing.

How tracks work

When your app starts up, the Shorebird updater asks the server: “Is there a new patch on the stable track for this release version?” If you have integrated package:shorebird_code_push, your app can instead ask for patches on a different named track. This makes it possible to route specific devices (e.g., your QA team’s phones) to a beta or staging patch without affecting production users.

flowchart LR
    A["patch --track=staging"] --> B{"Validate"}
    B -- "Issues" --> A
    B -- "OK" --> C["Promote to stable"]
    C --> D["All devices update"]

Built-in vs. custom tracks

Track	Description
stable	The default track. All devices receive patches from this track unless they explicitly subscribe to another.
staging	Commonly used for internal / CI validation before promoting to production.
beta	Commonly used for wider pre-production testing (e.g., QA teams, opt-in testers).
Any name	Custom tracks are created on demand, or with shorebird channels create.

Note

Track names are arbitrary strings. shorebird channels create and shorebird patches set-track accept names of up to 128 characters. Use whatever naming convention makes sense for your team. stable, beta, and staging are built-in names, so those tracks can’t be deleted.

Publishing a patch to a track

Pass the --track flag to any shorebird patch command. If you omit the flag, the patch is published to stable by default.

Android

Android

shorebird patch android --track=staging

iOS

iOS

shorebird patch ios --track=staging

macOS

macOS

shorebird patch macos --track=staging

You can use any custom track name:

shorebird patch android --track=beta
shorebird patch android --track=qa-team

Previewing a patch on a specific track

Use shorebird preview with the --track flag to run your app locally against a specific track’s patches:

shorebird preview \
  --app-id <your-app-id> \
  --release-version 1.0.0+1 \
  --track staging

This downloads the release and runs it on a connected device or emulator, applying the latest patch available on the specified track.

Promoting a patch between tracks

Once you’ve validated a patch on a staging track, you can promote it to stable without rebuilding. This pushes the patch to all production users.

Note

The Shorebird console and the shorebird patches promote command only promote a patch to stable. To move a patch to a different custom track, use shorebird patches set-track from the CLI.

Via the Shorebird console

Navigate to the release details page, click the ⋮ context menu next to the patch, choose Change Track, and select stable in the dialog that appears.

Via the CLI

Promote a patch directly to stable:

shorebird patches promote \
  --release-version 1.0.0+1 \
  --patch-number 1

To move a patch to any other track by name, use set-track:

shorebird patches set-track \
  --release 1.0.0+1 \
  --patch 1 \
  --track beta

Subscribing a device to a track

By default, devices always subscribe to the stable track. To have a device check a different track, you must:

1. Add package:shorebird_code_push to your app.
2. Set auto_update: false in your shorebird.yaml to disable the default background updater.
3. Call the updater manually with a track argument.

shorebird.yaml

app_id: your-app-id-here
auto_update: false

import 'package:shorebird_code_push/shorebird_code_push.dart';

final updater = ShorebirdUpdater();

// Subscribe this device to the beta track
await updater.update(track: UpdateTrack.beta);

// Or use a custom track name
await updater.update(track: UpdateTrack.custom('qa-team'));

Tip

UpdateTrack.stable and UpdateTrack.beta are convenience constants. For any other track name, use UpdateTrack.custom('your-track-name').

Listing patches by track

To see all patches for a release, including their track assignment, run:

shorebird patches list --release-version 1.0.0+1

The output shows each patch number, its active status, and the track it is currently assigned to.

Managing tracks from the CLI

As of Shorebird 1.6.121, the shorebird channels commands list, create, and delete an app’s tracks. Like other app commands, they read the app ID from shorebird.yaml in the current directory. Pass --app-id to run them from anywhere else, or --flavor to pick a flavor’s app ID. All of them support the global --json flag.

List tracks

shorebird channels list

1  stable
2  beta

Each line shows the track’s ID and name.

Create a track

shorebird channels create --name qa

You don’t need to create a track before publishing to it, since shorebird patch --track=<name> creates it for you. Use channels create when you want the track to exist before its first patch. The command fails if a track with that name already exists.

Delete a track

Devices on a deleted track stop receiving patches. There’s no confirmation prompt. Instead, you confirm by repeating the track’s name with --confirm-name, which works the same in a terminal and in CI:

shorebird channels delete --name qa --confirm-name qa

The built-in stable, beta, and staging tracks can’t be deleted.

Common patterns

Staging PatchesWalk through the full workflow of publishing to staging, previewing, and promoting to production.

Testing Patches with a Subset of UsersRoute specific devices (e.g. your QA team) to a beta track using account-based logic or a hidden UI.

Percentage-Based RolloutsGradually roll out patches to an increasing percentage of users using tracks and a cloud key-value store.

Frequently asked questions

How are Shorebird tracks different from Google Play testing tracks or Apple TestFlight?

Google Play testing tracks (internal, alpha, closed testing, production) and Apple TestFlight are app distribution mechanisms that control which users can install a given version of your app from the store. Shorebird tracks are a patch distribution mechanism that controls which running devices receive a Dart code update.

Shorebird has no built-in awareness of which Play track or TestFlight group a device is in. However, you can detect the install mechanism at runtime and use that signal to subscribe the device to the appropriate Shorebird track. See Testing Patches for more details.

Does rolling back a patch on one track affect other tracks?

No. Tracks are independent. Rolling back or disabling a patch on staging has no effect on patches on the stable track, and vice versa.

Can a device be on multiple tracks at the same time?

No. A device subscribes to exactly one track per update check. If your app logic changes the track dynamically (e.g., the user opts into a beta program), it will request patches from the new track on its next update check.

What happens if there is no patch on the requested track?

If no patch is available on the requested track for the current release version, the device continues to run the base release (or the last successfully applied patch). It does not fall back to the stable track automatically.

Can you promote a patch to a track other than stable?

Using shorebird patches set-track from the CLI, you can assign a patch to any track:

shorebird patches set-track \
  --release 1.0.0+1 \
  --patch 1 \
  --track beta

The Shorebird console and shorebird patches promote only target stable. Use set-track from the CLI when you need to move a patch to a different track.