Build & Release

This page walks through the end-to-end publishing flow for a forked Navigator app: developer accounts, namespace, store profiles, code signing, build automation with Fastlane, and the constraints that gate each store.

You should have already finished Configuration — env vars and a working debug build on simulator — and Theming & Branding for your icon, splash, and colors.

Prerequisites Checklist

Create Store Profiles

Apple — App Store Connect

1. Sign in to App Store Connect.
2. My Apps → + → New App.
3. Fill in:
   • Platform: iOS
   • Name: your APP_NAME
   • Primary Language
   • Bundle ID: matches APP_IDENTIFIER (must already exist under Certificates, Identifiers & Profiles → Identifiers; register it first if not).
   • SKU: an internal identifier of your choice.
   • User Access: who on your team can see the app.
4. In App Information, set the category and content rights.
5. In Pricing and Availability, set the price (free is fine) and the country list.
6. Prepare App Privacy answers — Navigator collects location continuously while in use and in the background, plus identifiers used for auth. Disclose accordingly.

Google — Play Console

1. Sign in to Google Play Console.
2. Create app.
3. Fill in:
   • App name: matches APP_NAME.
   • Default language.
   • App or game: App.
   • Free or paid: typically Free.
   • Accept the developer program policies declaration.
4. Complete the Dashboard → Set up your app checklist:
   • App access — provide test credentials for review.
   • Ads — declare whether the app contains ads.
   • Content rating — questionnaire.
   • Target audience — choose age groups (Navigator is for working drivers, so 18+).
   • News app — typically no.
   • COVID-19 contact tracing — no.
   • Data safety — declare location (background), email, phone, photos.
   • Government app — typically no.
   • Financial features — no, unless you collect COD via the app.
   • Health — no.
   • Store listing — title, short description, full description, icon, feature graphic, screenshots, video.
   • Main store listing → Privacy policy URL — required.

iOS — Build and Submit

Versioning

In Xcode, open ios/NavigatorApp.xcworkspace and set:

• MARKETING_VERSION (e.g. 1.4.0) — the version users see.
• CURRENT_PROJECT_VERSION (e.g. 42) — a monotonically increasing build number. Must be unique per TestFlight submission for a given marketing version.

Code Signing with Fastlane Match

Navigator ships with Fastlane lanes that use match with S3 storage for provisioning profiles, so multiple machines and CI can sign without manually shuffling certificates.

Required environment variables (see ios/fastlane/Fastfile):

The .p8 key file from App Store Connect must live at ~/.appstoreconnect/private_keys/AuthKey_<APPSTORE_API_KEY_ID>.p8.

Available Lanes

cd ios

# Build only (no upload)
bundle exec fastlane build_ios

# Build and upload to TestFlight (external testers enabled)
bundle exec fastlane deploy_testflight

# Build and upload to App Store (does NOT submit for review automatically)
bundle exec fastlane deploy_appstore

Each lane:

1. Loads the App Store Connect API key from env.
2. Creates an isolated ci-signing keychain.
3. Pulls certificates and provisioning profiles from S3 via match.
4. Builds with gym using manual signing and the match AppStore <APP_IDENTIFIER> profile.
5. Uploads to the chosen destination.
6. Tears down the keychain.

Submit for Review

After deploy_appstore, the build lands in App Store Connect under your selected version. In the App Store Connect UI:

1. Select the uploaded build.
2. Fill Version Information: what's new, screenshots (per device class), promotional text, support URL.
3. Fill App Review Information: contact, demo account credentials, notes for reviewers (mention that this is a fleet management app for commercial drivers, and that continuous location is required for live dispatch).
4. Submit for Review.

Typical review: 24–48 hours. Common reasons for rejection are covered in Troubleshooting.

Android — Build and Submit

Versioning

Set in your .env (or CI environment):

ANDROID_VERSION_CODE=42
ANDROID_VERSION_NAME=1.4.0

ANDROID_VERSION_CODE must increment for every upload, even across testing tracks.

Generate an Upload Keystore

If you don't already have one:

keytool -genkeypair -v \
  -keystore navigator-upload.keystore \
  -alias navigator-upload \
  -keyalg RSA -keysize 2048 -validity 10000

Store the resulting .keystore file somewhere safe (1Password, a sealed secret, an S3 bucket with KMS). If you lose it, you cannot publish updates without going through Google's Play App Signing key reset, which is a multi-week process.

Then export the signing envs the release build expects (already read in android/app/build.gradle):

export ANDROID_NAVIGATOR_APP_UPLOAD_STORE_FILE=/secure/path/navigator-upload.keystore
export ANDROID_NAVIGATOR_APP_UPLOAD_STORE_PASSWORD=...
export ANDROID_NAVIGATOR_APP_UPLOAD_KEY_ALIAS=navigator-upload
export ANDROID_NAVIGATOR_APP_UPLOAD_KEY_PASSWORD=...

Available Lanes

The Fastlane lanes (android/fastlane/Fastfile) all run gradle clean bundleRelease and upload an .aab to the named track:

cd android

bundle exec fastlane deploy_internal     # → Internal testing (instant, up to 100 testers)
bundle exec fastlane deploy_alpha        # → Closed testing (alpha)
bundle exec fastlane deploy_beta         # → Closed testing (beta) — use this for the 12-tester / 14-day requirement
bundle exec fastlane deploy_production   # → Production track

You need a Play Console service account JSON key referenced by Fastlane's json_key_file (typically set in android/fastlane/Appfile or via the SUPPLY_JSON_KEY env). Create it in Play Console → Setup → API access and grant it Release manager access for the app.

The Google 12-Tester Rule

Workflow:

1. bundle exec fastlane deploy_beta to upload your release .aab to the Beta closed track.
2. In Play Console → Testing → Closed testing, add testers via a Google Group or an email list of 12+ real Gmail accounts.
3. Share the opt-in URL with testers — each tester must click the URL and install the app from the resulting Play Store listing for the clock to start.
4. After ≥ 14 days with ≥ 12 active testers, you'll see an Apply for production access button on the testing page. Submit the form (Google may ask for screenshots showing testers in-app or feedback artifacts).
5. Once Google grants production access (typically a few days), promote the build via deploy_production or by selecting the closed-track release in the Production dashboard.

For corporate / organizational developer accounts, the 12-tester requirement does not currently apply — verify your account type in Play Console → Setup → Developer account → Account details.

Submit for Review

Once promoted to Production, Google reviews the release. Initial reviews can take 7+ days; subsequent updates are usually under 24 hours. Releases on internal/closed tracks are reviewed but typically go live the same day.

Version Bumping Convention

Keep public versions in sync across platforms. Build numbers are independent — Apple wants monotonic per marketing version, Google wants monotonic across all uploads.

CI / Continuous Delivery

The Fastfiles are CI-friendly:

• ensure_ci_keychain / cleanup_ci_keychain wrap iOS lanes so a fresh ci-signing keychain is created and destroyed per run.
• Match runs in MATCH_READONLY=true mode on CI to prevent accidental certificate regeneration.
• All sensitive values flow through env vars — wire them in via your CI provider's secret store (GitHub Actions, GitLab CI, CircleCI, etc.).

A typical GitHub Actions matrix would have one job for iOS (running on macos-latest) and one for Android (running on ubuntu-latest), each loading the relevant secrets and invoking the matching Fastlane lane on tag push.

Troubleshooting

Post-Launch

Once your app is live:

• Distribute the App Link (QR + URL) from Console → Admin → Fleet-Ops Config → Navigator App so drivers can configure the app with one scan.
• Wire crash and performance monitoring (Crashlytics, Sentry, or your provider of choice) into the release builds.
• For each subsequent release, follow the same flow: bump versions, run the deploy lane, submit for review.