apps/mobile and reports one version
train. A production commit gets one X.Y.Z and one build number B, and every
platform that ships that commit uses both.
Release ledger
The ledger is a set of annotated git tagsapp-b<B>, one per production commit
that ships. Git tags created by CI are the release owner’s chosen store for the
shared build counter; it has no database table, so a release needs only the
repository and the workflow token. Each tag points at its commit and carries
{ build, version, sha, shared, platforms } as JSON. scripts/app-version/allocate.mjs
reads and extends it. It runs before any build in mobile-deploy-stores.yaml
(Allocate shared app version) and in desktop-beta.yaml (release-status):
- If the commit is older than the newest entry, it is superseded, even when it
holds an entry from an earlier run, so builds always follow source order.
The superseded run publishes nothing and dispatches one release of the
production head for its own workflow (
mode=releasewithforce=truefor mobile, so the mobile tree gate cannot skip a store that failed earlier;dry_run=falsefor desktop). The head contains this commit, so its changes ship under a newer build even when the newer commit (for example a desktop-only change) never ran this channel’s workflow. - If an entry already points at the commit, both workflows and every rerun reuse it.
- Otherwise a new entry takes
B = previous B + 1and:X.Yfromapps/mobile/pubspec.yaml, owned by Release Please. When Release Please opens a new minor, its pubspec patch is the floor.Z + 1when shared app code changed since the previous entry (apps/mobile/**outside the platform directories).- The same
X.Y.Zwhen only platform inputs changed (apps/mobile/{ios,android,macos,windows,linux}/**,apps/mobile/vendor/record_ios/**,scripts/mobile-deployment/**,scripts/desktop-deployment/**). The entry records those platforms, and release surfaces label the build0.28.0 (build 1000005, android fix). Files that never ship (apps/mobile/{test,integration_test,test_driver,docs,coverage,tool}/**and Markdown) count as neither. Paths are read NUL-delimited, and both sides of a rename are classified. Bone above the highestapp-b<B>ref name, including lightweight or malformed refs, so a reserved number is never reused.
- The ref is created through the GitHub refs API, which is atomic. A workflow that loses the race (HTTP 422) re-fetches the ledger tags and replans, with at most five attempts. A commit the checkout lacks is fetched before any ancestry check.
git fetch origin '+refs/tags/app-b*:refs/tags/app-b*'), so every entry is visible. Annotations
are validated strictly: exact keys, a bounded X.Y.Z, known platform names
only, and a target that matches the ref. An invalid annotation is ignored but
its number stays reserved. Outputs are checked again before they reach
GITHUB_OUTPUT.
Protect the ledger with repository tag rulesets on app-b* only after a
dedicated writer exists, and restrict creation before locking entries:
- Create a GitHub App with
contents: write. Store its credentials in arelease-ledgerenvironment limited to theproductionbranch, and switch the allocation steps to a token minted from it (actions/create-github-app-token). The shared GitHub Actions actor is not enough, because any workflow with a write-capable token could create entries. - Add a ruleset with Restrict creations and that App as its only bypass actor.
- Then add a separate ruleset with Restrict updates and Restrict deletions and no bypass actors. A bypass applies to a whole ruleset, which is why the two are separate.
0.27.27 and build 1000000. That is above desktop
desktop-v0.27.26, mobile 0.27.20 and every Play version code (578001), so
no store or updater sees a version go backwards.
Allocation needs contents: write for tag refs only. The Windows Store draft
workflow keeps read-only permissions and runs allocate.mjs --reuse-only. It
fails when no desktop or mobile release has allocated the commit yet.
Platform mapping
Desktop releases are tagged
desktop-v<X.Y.Z>-<B>, and desktop builds embed
DESKTOP_RELEASE_RUN_ID=<B>. The Windows runner resource reads Flutter’s
generated version: the numeric fields carry X,Y,Z,0, and the
ProductVersion string carries X.Y.Z+B, which package_info_plus reports to
the updater. CI fails a Windows build whose executable reports another value.
Windows builds published before this wiring report 1.0.0, which ranks above
every 0.x release, so those installs need a one-time manual update from
/download. The in-app updater orders releases by X.Y.Z and
then by that suffix, so a desktop-only rebuild of the same X.Y.Z reaches
installed apps.
The Windows Store cannot accept a second package with the same version, so a
Windows-only fix reaches the Store only with the next shared patch. The Store
draft reads the ledger before compiling and checks that the executable reports
the ledger version.
Reruns and guards
A failed-job rerun keeps its earlier allocation outputs. So right before every upload, distribution and desktop publication,allocate.mjs --assert-current
re-checks source order through GitHub’s compare API (job checkouts are
shallow). The step fails when a newer commit holds the ledger, and a
release-head-when-stale job then dispatches one release of the production
head. The same check runs again after slow steps: after TestFlight
processing, right before beta-group assignment (LEDGER_RECHECK). The
scheduled review retry runs it too, resolving the selected build’s commit from
its ledger entry. To recover that build’s upload notes, it searches one-day
windows across the history artifact’s 14-day retention, because GitHub returns
at most 1,000 runs per filtered search. The check runs only while that build
still needs external delivery
(not yet approved or in review). When it is stale, the retry dispatches one
release of the production head, so external testers get a newer build instead
of waiting on one that can never ship. It skips the dispatch when a run that
can publish is already queued or running: a production push, or a dispatch
titled Mobile Store Deployment (release). Queued review retries never
count. It also runs after
the desktop draft upload, right before the release goes public. What remains
is the few seconds between that last check and the store call.
The mobile store gate compares against the newest run that attempted the
stores, and only if that run’s jobs show every enabled store verifiably
accepted its tree. For the Mac App Store, while MAC_APP_STORE_ENABLED is
true, that means its Apple acceptance step succeeded, not only its job. A
newer partial attempt yields no baseline. For example, tree B reached
TestFlight but Google Play failed. Even if production reverts to an older,
fully delivered tree, the next run publishes so both stores match again. The
gate reads jobs from every attempt of a run (filter=all, every page), so a
rerun can’t hide an earlier partial delivery. Artifacts written by older runs
count only once those jobs prove delivery.
Each channel also refuses a build below one it already delivered, so an older
run that finishes late can never move testers back:
- each workflow’s concurrency queue keeps that channel’s runs in production order;
- right before an upload or distribution, each channel re-checks its own store (below).
-
Apple (iOS and Mac App Store): before building,
apple-guard.mjslooks up buildBin App Store Connect. If it already exists with the same version, the job skips the build and upload and resumes at verification. AFAILEDorINVALIDbuild stops the run, because Apple never accepts that number again; the fix ships with the next production commit. The guard runs again right before each upload; if the build became visible meanwhile, the upload is skipped. After processing, TestFlight distribution and the scheduled review retry refuse when a newer iOS build was uploaded in any processing state. The Mac job waits for Apple to report the buildVALID(apple-guard.mjs --wait). The guard also refuses a version whose App Store train is released or approved, a version below a train TestFlight already holds, and a train that already has a newer build. -
Google Play: the Android job skips the upload when the internal track
already has
B, and fails when internal or a promoted track already serves a newer version code. The upload and promotion edits re-read the internal track before writing, so a release that went live in between is never replaced or outranked. -
Desktop: a rerun reuses the commit’s tag. When the first attempt
published a verified subset, the rerun adds only the missing platform assets
and never replaces a published one; a digest mismatch fails the run. The rerun
must carry verified packages for every platform already on the release, since
the refreshed notes list them all. A rebuilt package can differ byte for byte
(a signed installer is re-timestamped). The published asset then stays as it
is, and the notes describe it with its published digest and size. Its
signature was checked only by the run that published it, so the notes make
no signing claim for it and ask users to verify it. Notes describing a new package go out
before the package does. After a failed upload, the notes are rewritten to
list exactly the packages GitHub accepted. Publication also refuses when a
newer desktop ledger build has already shipped. A draft or another commit holding the tag
still blocks publication. The Debian package version is
X.Y.Z-B, and CI checks the emitted package metadata.
Beta channel status
After a store verifies a build, its pipeline publishes the facts as public JSON on the rollingapp-release-status prerelease:
https://github.com/tutur3u/platform/releases/download/app-release-status/ios.json(TestFlight)https://github.com/tutur3u/platform/releases/download/app-release-status/android.json(Google Play internal)https://github.com/tutur3u/platform/releases/download/app-release-status/desktop.json(desktop GitHub release)
{ schema: 1, platform, channel: "beta", store, version, build, label, sha, publishedAt }.
The pipeline first uploads an immutable <platform>-<build>.json record to the
shard release app-release-status-<platform>-<floor(build / 500)>, which keeps
each release below GitHub’s asset limit. It then moves the <platform>.json
pointer on app-release-status forward:
- the pointer never drops below the highest uploaded record across all shards (the release list is scanned to the end, and the pointer is left alone if it cannot be), so an older retry repairs a missing pointer with the newer build;
- a pointer that cannot be read is never overwritten;
- a failed upload’s leftover
starterasset is cleared before a retry.
*_EFFECTIVE_VERSION workspace config,
which a person sets after the public release is live.
Regression coverage: scripts/app-version/ledger.test.mjs (derivation,
monotonic and reserved builds, same-commit reuse, supersession, the create
race, read-only reuse, strict annotations, classification, MSIX mapping and
the Apple guard), scripts/app-version/beta-status.test.mjs,
scripts/desktop-deployment/release-topup.test.mjs, and the ledger cases in
release-history.test.mjs and play-beta.test.mjs.