meshcore-sar_android/docs/google-play-release.md

Google Play Release Runbook

Purpose

This runbook prepares and ships the Android release build for com.meshcore.sar.meshcore_sar_app.

Distribution Modes

• GitHub release: signed APK for direct install or manual distribution.
• Google Play: signed AAB uploaded through Fastlane to Play internal testing and, for non-prerelease GitHub releases, production.

Required Secrets and Local Files

GitHub Actions secrets for dz0ny/meshcore-sar:

• ANDROID_KEYSTORE_BASE64
• ANDROID_KEYSTORE_PASSWORD
• ANDROID_KEY_ALIAS
• ANDROID_KEY_PASSWORD
• GOOGLE_PLAY_SERVICE_ACCOUNT_JSON

Local files used to seed the secrets:

• android/key.properties
• release keystore referenced by android/key.properties
• /Users/dz0ny/android-keystores/fastlane-480919-0cb30c62db50.json

The Play Console service account must have release access for com.meshcore.sar.meshcore_sar_app.

CI Release Flow

The release flow runs from .github/workflows/build-artifacts.yml when a GitHub release is published.

Android release steps:

1. Validate all Android signing and Google Play secrets.
2. Recreate android/release-keystore.jks and android/key.properties from GitHub secrets.
3. Build the signed APK with flutter build apk --release.
4. Build the signed Play AAB with flutter build appbundle --release.
5. Upload the APK and AAB as GitHub release assets.
6. Upload the AAB to Play internal testing with bundle exec fastlane android internal.
7. Upload the AAB to Play production when the GitHub release is not marked as prerelease.

The same workflow also builds Linux, macOS, Windows, iOS unsigned, and web artifacts.

Versioning Rules

• Version source of truth: pubspec.yaml.
• Android versionCode is the number after +.
• versionCode must always increase for Play uploads.
• make bump, make build, and make bundle increment the version.
• Use make build-no-bump or make bundle-no-bump only when intentionally rebuilding the same version locally.

Manual Build Commands

Run commands from the repo root.

flutter build apk --release
flutter build appbundle --release

Repo shortcuts:

make build
make bundle
make build-no-bump
make bundle-no-bump

Fastlane Lanes

Run commands from android/.

bundle exec fastlane android direct_apk
bundle exec fastlane android internal
bundle exec fastlane android production

Set SKIP_ANDROID_BUILD=1 when an AAB has already been built and Fastlane should only upload it.

SKIP_ANDROID_BUILD=1 GOOGLE_PLAY_SERVICE_ACCOUNT_JSON="$(cat /Users/dz0ny/android-keystores/fastlane-480919-0cb30c62db50.json)" bundle exec fastlane android internal

Expected Artifacts

• APK: build/app/outputs/flutter-apk/app-release.apk
• AAB: build/app/outputs/bundle/release/app-release.aab
• Release APK asset: meshcore-sar-<tag>-android.apk
• Release AAB asset: meshcore-sar-<tag>-play.aab

Internal Testing Release Checklist

1. Confirm pubspec.yaml version is correct and versionCode increased.
2. Confirm android/key.properties points to the release keystore for local builds.
3. Confirm all five GitHub Actions secrets exist.
4. Publish a prerelease in GitHub to build assets and upload Play internal testing without production promotion.
5. Install from the internal testing track on a real Android device.
6. Smoke test startup, permissions, map, messaging, telemetry, and offline map behavior.

Production Release Checklist

1. Complete internal testing validation first.
2. Confirm Play Console forms are current:
   • App content
   • Data safety
   • App access
   • Ads declaration
   • Content rating
3. Confirm store assets are current:
   • app icon
   • feature graphic
   • phone screenshots
   • tablet screenshots if used
   • support URL
   • privacy policy URL
4. Publish a non-prerelease GitHub release.
5. Confirm the GitHub release has the APK and AAB assets.
6. Confirm Play Console has the new internal and production release entries.

Rollback Rules

• Never reuse or lower an Android versionCode.
• If a Play release is bad, halt rollout in Play Console and ship a new higher-version fix.
• Keep GitHub direct APK and Play AAB artifacts separate; do not upload APKs to Play.