Fixing a Flutter app without waiting for Google Play: setting up Shorebird the careful way
· 5 min read
Code push lets you fix Dart code on users' phones in minutes. It also lets you break them in minutes. This is how I set it up for Jaylak's customer and driver apps: signed patches, staging first, promotion without rebuilding, and rollback.
Jaylak has two Flutter apps: one for customers and one for drivers. When a driver app has a bug at 8 pm on a Friday, waiting a day or more for a store review is not a small problem. Orders are still coming in.
Shorebird adds code push to Flutter. You build your store release with Shorebird, and later you can send a patch, new Dart code, that installed copies download in the background and run on the next launch. No store review is needed for Dart-only changes.
A system that can change code on every user's phone in minutes is also a system that can break every user's phone in minutes. So the work was not "add the package". The work was making a patch hard to send by accident and easy to take back.
Where this stands: both Android apps have signed Shorebird baselines registered and verified on an emulator in CI, and the patch workflow is merged. A real patch on a physical device, with a rollback, is the next step. This post is about the setup, not a war story about patches.
Decision 1: two apps, two identities, two keys
The customer and driver apps are separate Shorebird apps with separate IDs. Each one has its own patch signing key. The public key is built into the baseline release, and the private key never goes into the repo. It lives in an encrypted local store and in GitHub environment secrets, and only the release environments can read it.
A signed patch means a leaked Shorebird token is not enough to push code. Without the private key the app rejects the patch. And with separate keys, a customer-app patch cannot reach drivers by mistake.
Decision 2: every patch goes to staging first
The patch workflow has four separate operations, and each one does one thing:
| Operation | What it does |
|---|---|
validate |
tests and a dry-run build, uploads nothing |
stage |
uploads a signed patch to the staging track only |
promote |
moves that same patch to stable, without rebuilding it |
rollback |
stops serving a patch and records what users should fall back to |
promote is the important one. It never rebuilds, because a rebuild is a different binary from the
one you tested. It takes the patch ID, the source commit and the device test record, checks that all
three belong to the same app, platform and release, and then promotes that exact patch. "Promote the
latest patch" is not an option on purpose.
Decision 3: pin everything a patch depends on
A Shorebird patch has to match the release it patches, so the workflow pins every input:
- The Flutter version of each baseline is fixed and recorded (3.41.2 here), not "whatever CI has today".
- The Shorebird CLI version is pinned too. Pinning the GitHub Action to a commit is not enough, because the action downloads a CLI on its own.
- The source commit is a reviewed SHA, never a branch that can move while the job runs.
- The production config comes from the stored release config, not from a dev file or a secret that changed since the baseline.
Decision 4: the app never waits for the updater
Updates download in the background on the default stable track. There is no "updating…" screen,
and the app is never force-restarted in the middle of an order or a delivery.
For debugging, the app reads the current patch number locally, with a 250 ms timeout, and adds it to every Sentry event:
Future<String> readCodePushPatchTag({PatchIdentityReader? reader}) async {
try {
final source = reader ?? _RuntimePatchReader();
if (!source.isAvailable) return 'unavailable'; // web, debug, or no Shorebird engine
final number = await source.readCurrentNumber().timeout(const Duration(milliseconds: 250));
return number?.toString() ?? 'base';
} on Object {
return 'unknown';
}
}
It never calls the network, never downloads anything and never blocks startup. When a crash report
comes in, I can see whether the phone was running the store release (base) or patch 3, which is
the first question you ask once code push exists. Web and debug builds never create the updater, so
the normal Flutter workflow is unchanged.
What the setup actually caught
- A full disk, not a broken build. The first Android release failed on CI. The cause was the runner running out of disk during Gradle/R8. Shorebird was fine. Freeing space fixed it.
- Windows security policy. Windows Application Control blocked part of Shorebird's Dart tooling locally. I did not weaken the policy. Release builds run on Linux in GitHub Actions.
- Emulator noise. The first startup checks showed ANR dialogs from the launcher. I gave the emulator more memory, skipped the Google setup wizard and added a check that the app window really has focus. After that, both apps passed the startup check without a rebuild.
- iOS is a separate project. iOS signing, distribution profiles and a real iPhone are not set up yet, so iOS is deferred instead of half-configured. Each app on each platform gets its own release record, because the same version number does not mean the same patch on both.
If you are about to add code push
- Sign your patches from the first baseline. You cannot add the public key to installs that already exist.
- Stage, then promote the exact same patch. Never rebuild between testing and release.
- Pin Flutter, the CLI and the source commit. A patch built on a different toolchain is a gamble.
- Know which patch crashed. Put the patch number in your crash reports before you need it.
- Practice the rollback before the emergency. A rollback you have never run does not count as a plan.
Code push does not replace store releases. Native changes, new permissions and new plugins still go through Google Play. What it gives you is a fast, signed and reversible way to fix Dart bugs while orders keep coming in.