---
title: "Staging Patches"
description: "Stage, validate, and promote patches"
---

[Pushing a patch to staging track](https://app.arcade.software/share/n22dgnzUR0qwvjNciQ2i)

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

New to tracks?

Tracks are named deployment channels that control which devices receive a patch. See the [Tracks](/code-push/tracks) reference page for a full explanation.

## Prerequisites

[Section titled “Prerequisites”](#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

[Section titled “Create a project”](#create-a-project)

Note

This guide walks through the process of creating a new project from scratch. To apply these changes to an existing project, skip this step and read ahead.

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

[Section titled “Create a release”](#create-a-release)

Now that the apps have been created on Shorebird, releases need to be created (one for each platform), using the `shorebird release` command.

* Android

  Android

  ```
  shorebird release android
  ```

* iOS

  iOS

  ```
  shorebird release ios
  ```

* macOS

  macOS

  ```
  shorebird release macos
  ```

Verify the releases were created successfully by visiting the [Shorebird console](https://console.shorebird.dev).

You should also [submit the generated app bundles to the Play Store](/flutter-concepts/releasing-flutter-apps/android/) and [submit the generated IPA to the App Store](/flutter-concepts/releasing-flutter-apps/ios/).

## Creating a patch

[Section titled “Creating a patch”](#creating-a-patch)

Now that the releases are on the Play Store and App Store, a patch can be created using `shorebird patch`. For the sake of this example, 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 the changes have been applied, create a patch:

* Android

  Android

  ```
  shorebird patch android --track=staging
  ```

* iOS

  iOS

  ```
  shorebird patch ios --track=staging
  ```

* macOS

  macOS

  ```
  shorebird patch macos --track=staging
  ```

## Preview the release

[Section titled “Preview the release”](#preview-the-release)

To 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, the white `Scaffold` should still be visible, 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. Congratulations, you’ve validated your patch in the staging environment 🥳

## Promote the patch

[Section titled “Promote the patch”](#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](https://console.shorebird.dev). 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](/_astro/staging_patches_patch_context_menu.dLLFppkB_2NlYX.webp) ![Screenshot of the 'switch track' dialog](/_astro/staging_patches_change_track_dropdown.CSHqpFNt_Z1wxliA.webp)

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 🎉