Staging Patches

This guide will walk through how to validate a patch in Shorebird’s staging environment before promoting the patch to production.

Prerequisites

This guide assumes the Shorebird command-line is installed on your machine and that you are logged into an account. Refer to the getting started instructions for more information.

Create a Project

Create a new project using shorebird create example --empty.

This will create a shorebird.yaml file in the root of your project. This file contains your Shorebird app_id. Your app_id is not secret and can be checked into source control and freely shared.

The generated shorebird.yaml should look something like:

# Your app_id is not a secret and is just used to identify your app
# when requesting patches from Shorebird's servers.
app_id: ee322dc4-3dc2-4324-90a9-04c40a62ae76
# auto_update controls if Shorebird should automatically update in the background on launch.
# If auto_update: false, you will need to use package:shorebird_code_push to trigger updates.
# https://pub.dev/packages/shorebird_code_push
# Uncomment the following line to disable automatic updates.
# auto_update: false

Create a release

Now that we’ve created our apps on shorebird, we need to create releases (one for each platform). To create a release, we’ll use the shorebird release command.

shorebird release android

shorebird release ios

shorebird release macos

We can verify the releases were created successfully by visiting Shorebird console.

You should also submit the generated app bundles to the Play Store and submit the generated ipa to the App Store.

Creating a patch

Now that we have our releases on the Play Store and App Store, we can create a patch using shorebird patch. For the sake of this example, let’s set the backgroundColor of the Scaffold to Colors.cyan in lib/main.dart:

import 'package:flutter/material.dart';

void main() {
  runApp(const MainApp());
}

class MainApp extends StatelessWidget {
  const MainApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(
+       backgroundColor: Colors.cyan,
        body: Center(
          child: Text('Hello World!'),
        ),
      ),
    );
  }
}

Now that we’ve applied the changes, let’s create a patch:

shorebird patch android --track=staging

shorebird patch ios --track=staging

shorebird patch macos --track=staging

Preview the release

Next, preview the app release locally on a device or emulator, use shorebird preview.

# Preview the release in the staging environment
shorebird preview --track staging --app-id ee322dc4-3dc2-4324-90a9-04c40a62ae76 --release-version 1.0.0+1

Shorebird will download the release and run it on your device in the staging environment.

The first time the app is re-launched, we should still see the white Scaffold and shorebird will detect and install the patch in the background. Kill and re-launch the app a second time to see the applied patch with the cyan Scaffold background.

If all went well, you should see the patch was applied after re-launching the app a second time. Congrats, you’ve validated your patch in the staging environment 🥳

Promote the patch

Now that you have validated the patch, you can push the patch to all devices by promoting it to production from the Shorebird console. Navigate to the release details page, choose “Change Track”, and select “stable” in the dialog that appears.

Screenshot of the 'switch track' option in the patch context menu

You can also use the Shorebird CLI to promote the patch.

You can promote the patch to the stable channel using the following command:

shorebird patches set-track --release-version 1.0.0+1 --patch-number 1 --track stable

At this point, you have a setup which allows you to preview patches locally before promoting them to production 🎉