Repository navigation
epic(shorebird): make emergency patches independent of main #7841
Description
Overview
Make Shorebird a dependable emergency recovery path for publicly distributed iOS and Android releases without freezing main or shipping every Dart change merged since the release.
The current Codemagic patch workflow requires main and rejects a patch after any blocked path lands. The new operating model uses a release-specific patch line rooted at immutable release provenance, with minimal reviewed backports, staging validation, and explicit stable promotion.
This epic is the source of truth for the policy, implementation, operational drill, decisions, and completion status. Keep its child checklist current as work lands.
Goals
- Build emergency patches from the exact provenance-recorded release baseline.
- Keep normal development on
mainmoving after a store release. - Ship only the minimal reviewed Dart fix plus any previously active fixes for that release.
- Preserve signing, provenance, configuration matching, staging, explicit promotion, and rollback protections.
- Prove the runbook on staged iOS and Android releases before relying on it in production.
Scope and decisions
- Shorebird remains an emergency repair mechanism, not a normal feature-delivery channel.
- Product fixes land on
mainfirst. Release patch lines contain reviewed backports and are never merged back intomain. - Each newer patch for a release must preserve all fixes in the currently active patch because only one patch is active at a time.
- Native, engine, plugin-native, bundled-asset, and broad dependency changes require a store release.
- The first implementation retains the conservative pubspec guard; precise pure-Dart dependency support is deferred until there is a demonstrated need.
- Store release builds continue to use
shorebird release. Zapstore APKs and macOS remain outside the current patch path.
Child work
Child issues are linked through GitHub sub-issues and are the authoritative completion checklist.
Success criteria
- The workflow accepts only an intentional release patch branch descended from the recorded baseline.
- An advanced
main, including later native or asset changes, cannot contaminate or prevent an isolated release backport. - The runbook defines eligibility, authorship/review, cumulative patches, validation, promotion, monitoring, rollback, and retirement.
- Automated tests pin all safety properties.
- A staged two-platform drill demonstrates first patch, cumulative second patch, and rollback.
Existing related work
- Related to ci(shorebird): move CI credentials to a dedicated service identity #7200 (dedicated CI service identity).
- Related to chore(legal): verify Shorebird updater licenses appear in Open Source Licenses #7206 (updater license verification).
These remain independent and do not block this epic unless the drill exposes a direct dependency.
Metadata
Metadata
Assignees
Labels
Type
Projects
- Status
Activity
NotThatKindOfDrLiz commentedon Aug 19, 2026
Status — 2026-08-18
shorebird-patch/**; deletion and non-fast-forward updates are prohibited.The epic remains the rollout source of truth; do not close it when #7844 merges.
NotThatKindOfDrLiz commentedon Aug 19, 2026
Status — 2026-08-19 (afternoon)
#7844 merged as
4aaca98a54. The remaining child, #7843, is now in progress on iOS and blocked on Android.iOS
The patch line
shorebird-patch/ios/1.0.21+851exists, is pushed, and validates. Full evidence in #7843. The epic's central success criterion — "An advancedmain, including later native or asset changes, cannot contaminate or prevent an isolated release backport" — is now demonstrated against the real repository rather than fixtures:mainsits 18 commits past the recorded baseline, the isolated backport validates, andmainitself is rejected as a patch source.Remaining on iOS is the part static checks cannot cover: run
ios-patch, install, verify on device, add a cumulative second patch, roll back.Android
Blocked, and worth recording as a real gap rather than a scheduling detail:
divinevideo/divine-release-provenancecontains onlyreleases/ios/. All three Android Shorebird releases (1.0.20+714,+716,+719) predate automatic provenance and therefore fail closed exactly as designed. An Android store release with a recorded baseline has to exist before Android is patchable at all — the workflow is correct today but has never had a valid input.That also means the epic cannot close on iOS evidence alone; the success criteria name both platforms.
Runbook corrections
Two gaps found while preparing the line, both in #7917: a fresh patch worktree fails the pre-push analyzer for a missing
.dart_toolrather than anything in the backport, and the patch-source validator is deliberately absent from lines whose baseline predates #7844.Separately, #7918 records the internal TestFlight tester groups in the runbook. Not part of this epic, but adjacent release-operations wiring that #7801 left invisible from the repo.
The epic stays open as the rollout source of truth.
NotThatKindOfDrLiz commentedon Aug 20, 2026
Status — 2026-08-20: the goal is production hot-fix, and production is not yet patchable
Recording the clarified objective, because it reorders the remaining work.
The point of this epic is not the drill. It is to fully integrate Shorebird and ship a Shorebird-built release through App Store review, so that a live production build can be hot-fixed without a second review cycle. The drill is the gate before committing to that submission.
Production is currently not patchable at all
The live App Store build is
1.0.21+849, recordedpatchable: false. It predates automatic provenance and its historical dart-defines cannot be reconstructed, so the workflow fails closed on it — correctly.1.0.21+850and+851arepatchable: truebut TestFlight-only, and the1.0.21App Store train is closed:ios_store_version_preflight.rbrequires a strictly greater marketing version than the approved one, so the next store build must be1.0.22.mobile/pubspec.yamlstill reads1.0.21+820and would fail that preflight today.So the capability this epic exists to deliver does not apply to any shipping build yet. It begins with #7980.
The safety gate is missing, and must ship with the capability
Shorebird replaces App Store review with a validate-then-promote sequence. On iOS the validate step is currently impossible:
shorebird previewcannot install anapp_store-signed artifact (0xe800801f, profile hasbeta-reports-activeand noProvisionedDevices), and an installed build only pollsstable. Full evidence on #7843.That means a hot-fix today would go straight to production users with neither review nor prior confirmation the patch applies. #7979 closes it, and belongs in the submission binary rather than after it — otherwise the first real incident is promote-and-pray.
Progress since the last update
ios-patchnow completes and patch 🏗️ [Infrastructure] Configure R2 Storage Buckets for Media Processing #1 is live onstagingfor1.0.21+851.849; see the comment there.Remaining, in order
1.0.21+851(first patch, cumulative second, rollback). Safe now because no App Store user runs851.1.0.22, cut the release carrying task: add a staging-track patch validation affordance to developer options #7979, ship it through review. This is the release that makes production hot-fixable.divinevideo/divine-release-provenancehas noreleases/android/. Unlike iOS, Android can useshorebird previewnormally once one exists.The epic closes when a shipping App Store build is patchable and a patch against it has been validated without touching production — not when the drill passes.
NotThatKindOfDrLiz commentedon Aug 21, 2026
Correction: Android is no longer blocked
Earlier status said Android was blocked on the absence of any provenance-recorded release. That is resolved.
1.0.22+739is published, anddivinevideo/divine-release-provenancenow hasreleases/android/1.0.22+739.jsonwithpatchable: true— the first Android record in the repository. Getting there required #7987 / #7988: Shorebird's bundled Flutter precaches only host artifacts, soshorebird release androidhad been failing on a missingflutter.jar, andshorebird_installrm -rfs~/.shorebirdon any pin change, discarding what the old1.0.20Android releases had.The
1.0.22train is also open now (#7981), which is the version #7980 needs.The remaining Android blocker is different and smaller: the release was cut from
main's tip, so there is nothing to backport onto its patch line yet. Details on #7843.Revised state:
Three separate things that had never been exercised turned out to be broken, each invisible to static tests because the path had never run. That is the drill's actual return so far, ahead of any of its stated criteria.
NotThatKindOfDrLiz commentedon Aug 21, 2026
Status — 2026-08-21: drill complete; production releases remain
The two-platform manual drill in #7843 is complete. Liz confirmed that the iOS and Android first patch, cumulative second patch, and rollback checks all passed. #7843 is closed.
#7979 is also complete via #7995, so the staging-track validation affordance required for a safe shipping iOS release is now on
main. The1.0.22release train is already open via #7981.Remaining critical path
The epic remains open until patchable Shorebird-built releases are shipping on both stores and their provenance records are confirmed
patchable: true.[-]epic: make Shorebird emergency patches independent of main[/-][+]epic(shorebird): make emergency patches independent of main[/+]NotThatKindOfDrLiz commentedon Oct 4, 2026
Closing as completed based on Liz’s confirmation in this session that the Shorebird-built store artifacts are live on both platforms. The two-platform patch drill was confirmed complete in #7843. Exact production build numbers were not provided in this session; the provenance versions checked during review are not being asserted as the live store versions. Remaining privacy-disclosure work continues in #7980 and #8850.