pleno-vue/docs/mobile-artifacts.md

Mobile Store Artifacts

The Mobile Store Artifacts workflow builds signed Android and iOS store artifacts from the Vue/Vite web app through Capacitor, then uploads them to Google Play and App Store Connect by default.

Use the Capacitor project under android/ for the Google Play Store package. The Bubblewrap/TWA files at the repository root are not the path used by mobile:android:bundle.

Triggers

• Manual: run Mobile Store Artifacts from GitHub Actions and optionally provide version_name, version_code, upload toggles, and Android track/status overrides.
• Tag: push a tag named mobile-vX.Y.Z; the workflow uses X.Y.Z as the store version name.
• Automatic store upload: after the Automated Tests workflow completes successfully on current master, GitHub Actions builds signed Android and iOS artifacts from that tested commit and uploads them to the stores.
• Stale workflow-run protection: if a newer commit reaches master before the mobile workflow runs, both store-upload jobs skip the stale commit.

Default upload behavior:

• Android uploads package io.truckwash.twa to the Google Play production track with release status completed.
• iOS uploads bundle io.truckwash.app to App Store Connect for TestFlight/App Review processing. Public App Store release still depends on App Store Connect review and release settings.
• Manual dispatch can disable either upload path while still producing signed GitHub artifacts.

Required Secrets

Store secrets are expected in the GitHub environment mobile-store-production.

Non-secret environment variables:

• ANDROID_PACKAGE_NAME=io.truckwash.twa
• ANDROID_AAB_PATH=android/app/build/outputs/bundle/release/app-release.aab
• PLAY_STORE_TRACK=production
• PLAY_STORE_RELEASE_STATUS=completed
• PLAY_STORE_USER_FRACTION only when using PLAY_STORE_RELEASE_STATUS=inProgress

Android:

• ANDROID_KEYSTORE_BASE64
• ANDROID_KEYSTORE_PASSWORD
• ANDROID_KEY_ALIAS
• ANDROID_KEY_PASSWORD
• GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64

iOS:

• IOS_CERTIFICATE_BASE64
• IOS_CERTIFICATE_PASSWORD
• IOS_PROVISION_PROFILE_BASE64
• IOS_KEYCHAIN_PASSWORD
• APPLE_TEAM_ID
• APP_STORE_CONNECT_API_KEY_ID
• APP_STORE_CONNECT_ISSUER_ID
• APP_STORE_CONNECT_API_PRIVATE_KEY_BASE64

The Google Play secret is a base64-encoded service-account JSON file with Android Publisher API access to the Play Console app. The App Store Connect private key secret is the base64-encoded .p8 API key file.

Local Checks

Run the native permission validation after changing Capacitor, native manifests, or store metadata:

npm run mobile:permissions:check

Build a local unsigned Android App Bundle for packaging verification:

npm run mobile:android:bundle:unsigned

Build a signed Play Console upload bundle after exporting the Android upload-key variables:

export ANDROID_KEYSTORE_FILE=/path/to/upload-key.jks
export ANDROID_KEYSTORE_PASSWORD=...
export ANDROID_KEY_ALIAS=...
export ANDROID_KEY_PASSWORD=...
npm run mobile:android:bundle

The signed Android bundle is written to:

android/app/build/outputs/bundle/release/app-release.aab

Upload a locally built signed App Bundle to Google Play after exporting the Play service-account secret and release metadata:

export GOOGLE_PLAY_SERVICE_ACCOUNT_JSON_BASE64=...
export ANDROID_PACKAGE_NAME=io.truckwash.twa
export ANDROID_AAB_PATH=android/app/build/outputs/bundle/release/app-release.aab
export MOBILE_VERSION_NAME=1.4.0
export MOBILE_VERSION_CODE=10400
export PLAY_STORE_TRACK=production
export PLAY_STORE_RELEASE_STATUS=completed
npm run mobile:android:play-upload

Use PLAY_STORE_RELEASE_STATUS=inProgress only with PLAY_STORE_USER_FRACTION set to a value greater than 0 and less than 1.

Android artifacts use package id io.truckwash.twa. iOS artifacts use bundle id io.truckwash.app.

The Android project currently targets SDK 36. Google Play requires new apps and updates to target Android 15/API 35 or higher starting August 31, 2025: https://developer.android.com/google/play/requirements/target-sdk

Play Store graphics are generated in the workspace-level playstoregraphics/ folder:

• App icon: playstoregraphics/universal/app-icon/truck-wash-icon-512.png
• Feature graphic: playstoregraphics/universal/feature-graphic/truck-wash-feature-1024x500.jpg
• Phone screenshots: playstoregraphics/phone/screenshots/
• 7-inch tablet screenshots: playstoregraphics/tablet-7/screenshots/
• 10-inch tablet screenshots: playstoregraphics/tablet-10/screenshots/
• Chromebook screenshots: playstoregraphics/chromebook/screenshots/

The native manifests declare camera and foreground location access for the store binaries. Keep the App Store Connect and Play Console privacy questionnaires aligned with the app's actual camera and location data handling before submitting a release.