Markdown

Store releases (App Store, Google Play and friends)

When your app ships through a store, the store hosts the binary — Stacklift doesn't, and you don't upload anything to Stacklift. The CLI records the build; you submit it to the store with whatever you already use.

The flow

bash
# 1. Build as usual
flutter build appbundle && flutter build ipa

# 2. Record the build in Stacklift. Version, build number and app id are read from the built files.
stacklift release create \
  --native android:build/app/outputs/bundle/release/app-release.aab \
  --native ios:build/ios/ipa/Runner.ipa

# 3. Upload to Google Play / App Store Connect with your usual tool (Fastlane, Xcode, Play Console …)

# 4. Tell Stacklift where it is. Optional, but it's what the dashboard shows.
stacklift store status 1.4.2 ios in-review
stacklift store status 1.4.2 ios released

Nothing is uploaded in step 2: the CLI hashes the file locally and sends the name, size, checksum, version, build number, git commit and CI link. The release is READY immediately.

What is read from the built binary

For an .ipa or .aab the CLI opens the finished file and reads the numbers the store will actually see: Info.plist inside the IPA (binary or XML), and the compiled AndroidManifest.xml inside the AAB (package, versionName, versionCode). Only that one small entry is read — never the whole archive — and nothing in it is executed. This wins over the project files, because the project can change between the build and the release. If the two disagree you get a warning ("The built binary is 1.4.2 but the project files say 9.9.9"); if --version contradicts the binary you are told the store will show the binary's version.

If both an IPA and an AAB are given and their versions differ, you get a warning and the most common one is used. Build numbers stay per platform.

.apk and other formats (MSIX, DMG, EXE …) are not opened; for those the project files below are used.

What is read from your project

When there is no readable binary (or for hosted artifacts), the CLI reads the version from the files your build already uses, and says where each came from:

StackVersion / build numberApp id
Flutterpubspec.yaml (version: 1.4.2+37)applicationId in Gradle, PRODUCT_BUNDLE_IDENTIFIER in Xcode
React Native, Capacitor, NativeScript, KMPNative files win: Gradle versionName/versionCode, Xcode MARKETING_VERSION/CURRENT_PROJECT_VERSION; package.json is the fallbacksame
Native Android / iOS / macOSGradle / Xcode projectsame
Expoapp.json (expo.version, ios.buildNumber, android.versionCode)bundleIdentifier, package
.NET MAUI / WPF / WinUI.csproj (ApplicationDisplayVersion, ApplicationVersion), Package.appxmanifestApplicationId, MSIX identity
UnityProjectSettings.assetper-platform identifier
Electron / Tauri / Compose Desktoppackage.json / tauri.conf.json / packageVersionbuild.appId / identifier

Only literal values are used. A Gradle property or an Xcode $(MARKETING_VERSION) is a build-time indirection, so it's reported ("not a literal, so it was not read") instead of guessed. If your iOS and Android versions disagree, you get a warning and the most common one is used; pass --version to choose. Build numbers stay per platform, so a Play versionCode of 30 and an App Store build of 31 are both kept.

Override anything with --version, --build-number or --runtime-version. For a store-only release runtimeVersion defaults to the version, since nothing is delivered to a runtime.

Set them once; they show on the project and on every release.

bash
stacklift store link ios https://apps.apple.com/us/app/glyph/id6740000000

or in stacklift.yaml (synced on release create, best effort: a CI token without project:update just skips it):

yaml
stores:
  ios: https://apps.apple.com/us/app/glyph/id6740000000
  android: https://play.google.com/store/apps/details?id=com.shokal.glyphwidget

The Google Play link is derived from your package name when you don't set one, and is shown as *derived*: it's where the listing will live, not proof it exists yet. The App Store link can't be derived (it needs Apple's numeric id), so add it once.

Links must be https and on the store's own host (apps.apple.com, play.google.com, apps.microsoft.com, …). Anything else — javascript:, http:, look-alike hosts, URLs with credentials — is rejected, because these render as hyperlinks.

Store status

built → submitted → in_review → released (or rejected, removed). Stacklift has no access to the stores, so this is what you tell it, with stacklift store status, the dashboard's selector, or --store-status on release create. release create sets built for you and never overwrites a status someone already recorded.

Devices and installs

If your app embeds a Stacklift SDK and calls check with its currentVersion, Stacklift knows which devices run which build — whatever delivered it:

swift
let manifest = try await client.check(CheckRequest(channel: "production", runtimeVersion: "1.4.2", currentVersion: "1.4.2", deviceId: DeviceIdentity.getOrCreate()))
// no OTA deployed? you get { updateAvailable: false, reason: "nothing_deployed" } and the check-in is still counted

The release page then shows active devices on this version in the last 30 days, per platform: a device counts toward the newest version it last reported, so it leaves the old release's count when it updates. Device ids are random, per install and hashed with the project id; Stacklift keeps no hardware or advertising ids.

What Stacklift can't do

  • Upload to the stores. Use Fastlane, Xcode, bundletool, the Play Console API.
  • See store download counts, ratings or review state. Those need the App Store Connect and Google Play Developer APIs. Integrations for them are planned, not built. Until then "downloads" means OTA downloads, and "devices" means devices that checked in through the SDK — a fraction of your store installs if the SDK isn't in every build.
  • Verify the store build. The checksum is whatever your CLI declared; Stacklift never sees the bytes, and labels it that way.
  • Deploy a store build to a channel. Store builds are never delivered to devices, so a release made only of them can't be deployed (the CLI skips --channel, the API refuses with an explanation).

Mixed releases

A React Native, Expo or Capacitor release can carry an OTA bundle *and* its store build. The bundle is hosted, verified, signed and deployable; the store build is recorded:

bash
stacklift release create --runtime-version 2.3.0 \
  --artifact ios:js-bundle:dist/ios.zip --artifact android:js-bundle:dist/android.zip \
  --native ios:build/App.ipa --native android:build/app-release.aab \
  --channel staging

In CI

yaml
- run: flutter build appbundle && flutter build ipa
- run: |
    stacklift release create \
      --native android:build/app/outputs/bundle/release/app-release.aab \
      --native ios:build/ios/ipa/Runner.ipa
  env: { STACKLIFT_TOKEN: ${{ secrets.STACKLIFT_TOKEN }} }

On GitHub Actions, GitLab CI, CircleCI and Bitrise the release links back to its pipeline run. Only those well-known variables are read — never the rest of the environment.