Skip to content

Android Release Configuration

Jump to bottom
Ejun edited this page May 10, 2026 · 7 revisions

Android Release Configuration

Android release builds must include the production Firebase client config so Firebase Core and Firebase Messaging initialize consistently.

Required CI Secret

  • ANDROID_GOOGLE_SERVICES_JSON_B64: base64-encoded contents of the production Android google-services.json for Firebase project ontime-c63f1.

The Android Play Internal Deploy workflow decodes this secret to android/app/src/release/google-services.json before running the Android release build. Generated google-services.json files are ignored and must not be committed.

The decoded file must include an Android client whose package name is club.devkor.ontime. Gradle validates this package match for release builds and through the focused validation task below.

Google Play Internal Testing Deploy

Use the Android Play Internal Deploy GitHub Actions workflow to build a signed Android App Bundle and upload it to the Google Play Internal Testing track as a draft release. The workflow runs automatically on pushes to main and can also be dispatched manually from main.

Configure a GitHub environment named staging for internal test distribution. Store these environment secrets there:

  • ANDROID_GOOGLE_SERVICES_JSON_B64: base64-encoded production Android Firebase config.
  • ANDROID_UPLOAD_KEYSTORE_B64: base64-encoded Google Play upload keystore.
  • ANDROID_KEYSTORE_PASSWORD: upload keystore password.
  • ANDROID_KEY_ALIAS: upload key alias.
  • ANDROID_KEY_PASSWORD: upload key password.
  • GOOGLE_PLAY_SERVICE_ACCOUNT_JSON: raw service-account JSON for the Google Play Developer API.

Store this environment variable in staging:

  • REST_API_URL: target API base URL passed to Flutter with --dart-define.

The deploy workflow runs package install, code generation, generated-file drift checking, analysis, tests, and then flutter build appbundle --release. It derives Android versionName from the pubspec.yaml version name and supplies ${{ github.run_number }} as Android versionCode:

flutter build appbundle --release \
  --build-name=<version name from pubspec.yaml> \
  --build-number=${{ github.run_number }} \
  --dart-define=ENV=staging \
  --dart-define=REST_API_URL="$REST_API_URL"

It uploads the signed .aab as a 14-day GitHub Actions artifact and creates a draft release on Google Play Internal Testing. If the optional release notes input is empty, the workflow uploads without custom release notes.

Keep pubspec.yaml as the source of truth for the manually managed public version name, such as version: 1.0.0+1. Android CI ignores the checked-in build suffix for Play uploads, so do not open PRs only to bump +2, +3, and similar build numbers. The generated github.run_number must still be greater than every previously uploaded Google Play build for club.devkor.ontime; duplicate or lower build numbers fail during the Google Play upload step.

Local Release Build

Create the release source-set config before building:

mkdir -p android/app/src/release
base64 --decode android-google-services.json.b64 > android/app/src/release/google-services.json
flutter build appbundle --release \
  --build-name=<version name from pubspec.yaml> \
  --build-number=<monotonic Android versionCode> \
  --dart-define=ENV=prod \
  --dart-define=REST_API_URL=<api-url>

On macOS, use base64 -D instead of base64 --decode.

Debug/local builds may run without Android Firebase config. Release builds fail clearly if android/app/src/release/google-services.json, android/app/google-services.json, or android/app/src/google-services.json is missing.

To validate only the Firebase config without requiring release signing inputs, materialize the ignored release config file and run:

cd android
gradle :app:validateAndroidGoogleServices

The task fails if the file is missing, invalid JSON, or missing a client_info.android_client_info.package_name entry for club.devkor.ontime.

Auth Fingerprints

Release SHA-1 and SHA-256 fingerprints must be added to Firebase after the release signing owner, upload key, and Play App Signing setup are finalized. Use docs/Android-Play-Signing-Fingerprints.md for the #454 checklist. Do not rotate or replace ANDROID_GOOGLE_SERVICES_JSON_B64 for fingerprint changes until the release owner confirms the final signing fingerprints.

Verification

Use the Android Play Internal Deploy GitHub Actions workflow to confirm CI can reproduce the signed release build with the configured secrets. For production readiness, also install a real Android release build and verify Firebase initializes and FCM token registration reaches the backend.

Clone this wiki locally