---
title: "Patch Several Releases"
description: "Ship one fix to every release your users still run, with a patch for each release, built in parallel in CI or by an AI agent."
---

A bug found today is often in more than the latest release. Users update from the stores at their own pace, so last week’s release and the one before it may still be on many devices. To reach all of them, patch each release that has the bug.

Each patch is for one release on one platform: a fix in three releases is three patches per platform. This guide shows how to build them from the right code, run them side by side in CI so three take about as long as one, and hand the routine part to an AI agent.

## Choose the releases

Patch the releases your users still run. The [Shorebird Console](https://console.shorebird.dev) shows each release’s active devices, and so does an [AI app connected to Shorebird](/account/ai-apps/) (“Which old versions are still out there?”). List the releases on a platform with:

```
shorebird releases list --platform android
```

A release with few users left may not be worth a patch: those users get the fix when they update from the store.

## Build each patch from its release’s code

A patch replaces all of the release’s Dart code with the code you build it from, so it must include the fixes from that release’s earlier patches. Build each patch from the release’s branch, which holds those fixes, with the new fix added. For one release:

```
git checkout release/v1.4.0
git cherry-pick <fix-commit>
git push
shorebird patch android --release-version 1.4.0+12 --track staging
```

Everything on the branch ships, so first check it has no commits from a patch you rolled back or rejected. Then the new patch adds only the fix. That keeps it small and, on iOS, keeps most of its code running natively; see [Link percentage and slow patches](/code-push/performance/#link-percentage-and-slow-patches). This needs a branch for each release; the [Development Workflow](/code-push/guides/development-workflow/) guide sets one up. If a release only has a tag, create its branch from the tag and cherry-pick the fixes from any patches the release already has.

You can build a patch for an older release from newer code, such as `main`, and `shorebird patch` builds it with the release’s Flutter version. That patch carries every Dart change made since the release, not only the fix, so test it as you would a new release. If native code or assets changed since the release, `shorebird patch` warns and asks whether to continue, or stops where it can’t ask, as in CI. On iOS, the more the code has changed, the more of it runs in the interpreter, and `shorebird patch` refuses a patch that [links below its minimum](/code-push/performance/#the-failure-below-20).

Each patch also needs the build flags its release used, such as `--dart-define` and `--flavor`. If they differ between releases, pass each release’s own; see [A patch uses the build flags of its release](/code-push/patch/#a-patch-uses-the-build-flags-of-its-release).

## Put the fix on each release’s branch

To patch several releases in CI, first cherry-pick the fix onto each release’s branch and push. Leave out any branch you’ve already done:

```
for branch in release/v1.4.0 release/v1.3.0; do
  git checkout "$branch" && git pull && git cherry-pick <fix-commit> && git push || break
done
```

The loop stops at the first branch where this fails. If the fix doesn’t apply cleanly, resolve it there and push. If the branch already has the fix, run `git cherry-pick --skip`. Then run the loop for the remaining branches. If a branch is protected, get the fix onto it through your usual pull request.

## Patch the releases in parallel in CI

A patch takes about as long to build as a release. To patch several releases at once, run one CI job per release. This GitHub Actions workflow takes a list of releases and builds an Android patch from each release’s branch in its own job, onto the `staging` track. It only reads your repository:

.github/workflows/patch-releases.yaml

```
name: patch-releases

on:
  workflow_dispatch:
    inputs:
      releases:
        description:
          'JSON list of releases, e.g. [{"version": "1.4.0+12", "ref":
          "release/v1.4.0"}, {"version": "1.3.0+9", "ref": "release/v1.3.0",
          "args": "--flavor prod"}]'
        required: true

permissions:
  contents: read

env:
  SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}

jobs:
  patch-android:
    runs-on: ubuntu-latest
    strategy:
      # One release failing doesn't stop the others.
      fail-fast: false
      matrix:
        release: ${{ fromJSON(inputs.releases) }}

    name: 🤖 Patch Android ${{ matrix.release.version }}

    steps:
      # Without a ref, checkout would build the default branch.
      - name: 🔎 Check Release Branch
        env:
          REF: ${{ matrix.release.ref }}
        run: test -n "$REF"

      - name: 📚 Git Checkout
        uses: actions/checkout@v7
        with:
          ref: ${{ matrix.release.ref }}

      - name: ☕️ Setup Java
        uses: actions/setup-java@v6
        with:
          java-version: '17'
          distribution: 'temurin'
          cache: gradle

      - name: 🐦 Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        with:
          cache: true

      - name: 🔐 Decode Keystore
        run:
          echo ${{ secrets.KEYSTORE }} | base64 --decode > ${{ github.workspace
          }}/keystore.jks

      - name: ✍️ Assemble Key Properties
        run: |
          echo "keyAlias=${{ secrets.KEYSTORE_ALIAS }}" >> ${{ github.workspace }}/android/key.properties
          echo "keyPassword=${{ secrets.KEYSTORE_PASSWORD }}" >> ${{ github.workspace }}/android/key.properties
          echo "storeFile=${{ github.workspace }}/keystore.jks" >> ${{ github.workspace }}/android/key.properties
          echo "storePassword=${{ secrets.KEYSTORE_PASSWORD }}" >> ${{ github.workspace }}/android/key.properties

      - name: 🧩 Shorebird Patch
        id: shorebird-patch
        uses: shorebirdtech/shorebird-patch@v1
        with:
          release-version: ${{ matrix.release.version }}
          platform: android
          track: staging
          args: '--verbose ${{ matrix.release.args }}'

      - name: 🔢 Report Patch Number
        env:
          VERSION: ${{ matrix.release.version }}
          LABEL: ${{ matrix.release.label }}
          PATCH_NUMBER: ${{ steps.shorebird-patch.outputs.patch-number }}
        run: |
          echo "Android $VERSION $LABEL: patch $PATCH_NUMBER" | tee -a "$GITHUB_STEP_SUMMARY"
```

Commit this file to your default branch first: GitHub only offers a manual run for a workflow that is on the default branch. Then run it from the **Actions** tab, or from a terminal with the [GitHub CLI](https://cli.github.com):

```
gh workflow run patch-releases.yaml \
  -f releases='[{"version": "1.4.0+12", "ref": "release/v1.4.0"}, {"version": "1.3.0+9", "ref": "release/v1.3.0"}]'
```

Each entry’s `ref` is that release’s own branch. If a release used its own build flags, add them to its entry as `args`, such as `"args": "--flavor prod"`. The patch action parses `args` as shell words, so treat this field like code, and don’t put secret values in it: anyone who can read the run can see them. If two entries share a version, as flavors can, add a `label` to tell them apart in the run’s summary. To single-quote a value containing `$` or spaces, keep the list in a file and pass it with `-f releases="$(cat releases.json)"`. If an older branch needs a different Java version, add a `java` field and use it for `java-version`.

For iOS, add a `patch-ios` job on a macOS runner, with this job’s `strategy` and its branch check, checkout and patch number steps, with the number’s label changed to iOS. Take the Shorebird, Xcode and signing setup from the iOS job in the [Development Workflow](/code-push/guides/development-workflow/#patch-phase) guide, and use this patch step:

```
- name: 🧩 Shorebird Patch
  id: shorebird-patch
  uses: shorebirdtech/shorebird-patch@v1
  with:
    release-version: ${{ matrix.release.version }}
    platform: ios
    track: staging
    args:
      '--export-options-plist ios/GHAExportOptions.plist ${{ matrix.release.args
      }}'
```

Each patch must build with its release’s Xcode, and a release’s iOS version can differ from its Android one. If yours do, add fields such as `ios_version`, `xcode` and `runner` to each entry and use them in this job.

Each job uses its own runner, so patching four releases takes about the time of one, and four times the runner minutes. If a job fails, fix the cause and run the workflow again for that release alone.

## Test and promote each patch

Each release gets its own patch on each platform, with its own patch number, which the workflow run’s summary lists. Preview each one on the staging track:

```
shorebird preview --release-version 1.4.0+12 --track staging
```

Then promote each patch, on every platform you patched, from the console or the command line:

```
shorebird patches promote --release-version 1.4.0+12 --patch-number 3
shorebird patches promote --release-version 1.3.0+9 --patch-number 5
```

If a release uses a flavor, add `--flavor` to these commands too. If testing rejects a patch, revert the fix on that release’s branch, or its next patch will ship the fix again. See [Staging Patches](/code-push/guides/staging-patches/) for more on the staging track.

## Let an AI agent run it

Choosing the releases, finding each one’s branch, checking that the fix applies and starting the workflow is routine work an AI coding agent can do. Save this as `.claude/skills/patch-releases/SKILL.md` in your repository for [Claude Code](https://docs.claude.com/en/docs/claude-code/skills), or paste the part after the header into any agent as a prompt. Edit the first step to say how your team names release branches.

.claude/skills/patch-releases/SKILL.md

```
---
name: patch-releases
description:
  Patch a fix onto several Shorebird releases at once. Use when asked to ship a
  fix to older releases, or to every release users still run.
---

1. Branches: each release has its own branch `release/v<version>`, where
   `<version>` is the `version` in `pubspec.yaml` without the `+<build>` part.
   If two releases share a version, ask which branch each one uses. (Edit this
   to match how your team names release branches.)
2. Run `git fetch`. Ask which commit is the fix if you weren't told. If it isn't
   a single non-merge commit, stop and ask. Ask which releases to patch. If you
   weren't told, list them with `shorebird releases list --json` (with
   `--flavor` if the app has flavors) and keep those `active` on the platforms
   the workflow patches. `active` only means the release finished uploading, so
   use Shorebird's MCP server if it's connected, or ask, to drop releases few
   users still run. Propose the ones the bug is in. Compare the code on each
   branch, because cherry-picks change commit hashes.
3. For each release, create a scratch worktree with
   `git worktree add --detach <dir> origin/<branch>` and run
   `git cherry-pick <commit>` there. Report any release where the fix doesn't
   apply cleanly and leave it out. If the cherry-pick stops as empty, the branch
   already has the fix: run `git cherry-pick --skip`, report it, and ask whether
   that release still needs a patch.
4. Check that the fix changes only Dart code and nothing in a platform directory
   such as `android/` or `ios/`, the assets in `pubspec.yaml` or native
   dependencies. A patch can't change those; if the fix does, stop and say so.
5. Show the releases, their branches and each branch's recent commits, and wait
   for approval. Say that everything on a branch ships, including any commit
   from a rolled-back patch. Then run `git push origin HEAD:<branch>` from each
   worktree that has the new commit. If a push fails, report it and leave that
   release out.
6. Write the releases to a temporary file as a JSON list with one entry each:
   `{"version": "<version+build>", "ref": "<branch>", "args": "<build flags>"}`.
   Ask for any build flags a release needs, such as `--flavor`, and leave out
   `args` if it needs none. Run
   `gh workflow run patch-releases.yaml -f releases="$(cat <file>)"`.
7. Report the run's link and, once it finishes, each release's patch number,
   which its job prints in the `Report Patch Number` step, and any job that
   failed, with its error.

However you finish, remove each scratch worktree with
`git worktree remove --force <dir>`. Never promote a patch from staging or roll
one back: a person tests each patch and promotes it.
```

The agent needs the GitHub CLI signed in, and Shorebird signed in or a `SHOREBIRD_TOKEN` to list releases. To let it answer which releases have the most users, also connect it to Shorebird’s [MCP server](/account/ai-apps/).
