Fastlane Setup for iOS & Android

What you'll learn

• Configuring Fastlane lanes for iOS and Android builds
• Setting up flavor-specific build configurations
• Managing code signing with Match
• Running deployments from CI or locally

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Xcode installed (for iOS builds)
• A Google Play Console and App Store Connect account
• Ruby and Bundler installed (gem install bundler)

Step 1: Locate the Fastlane Configuration

Fastlane is generated with every project by the flutter_modular_monorepo brick. There is no separate generate command. It lives inside the app package:

apps/<app_name>/
├── Gemfile
└── fastlane/
    ├── Appfile        # App identifier, Apple and Play Store credentials (read from env vars)
    ├── Fastfile       # Lane definitions
    ├── Matchfile      # Code signing config
    ├── Pluginfile     # Fastlane plugins (Firebase App Distribution)
    └── README.md      # Env vars, lanes and artifact naming

Install the Ruby dependencies once:

cd apps/<app_name>
bundle install

Step 2: Set Environment Variables

The Appfile and Matchfile read credentials from the environment, so nothing secret is committed. The main ones:

Variable	Used for
APP_IDENTIFIER	Bundle ID / package name (defaults to the generated one)
APPLE_ID, TEAM_ID, ITC_TEAM_ID	iOS signing and App Store Connect
MATCH_GIT_URL, MATCH_PASSWORD	Certificates repo for match (password needed in CI)
GOOGLE_PLAY_JSON_KEY	Path to the Play Store service account key
FIREBASE_ANDROID_APP_ID_<FLAVOR>, FIREBASE_IOS_APP_ID_<FLAVOR>	Firebase App Distribution (DEVELOPMENT, STAGING, PRODUCTION)
SLACK_WEBHOOK_URL	Optional build notifications

The full list is in the generated apps/<app_name>/fastlane/README.md.

Step 3: Configure Code Signing with Match

Match stores your certificates and profiles in a private Git repo, keeping your team in sync. Point MATCH_GIT_URL at that repo, then sync:

cd apps/<app_name>
bundle exec fastlane match adhoc       # Firebase distribution
bundle exec fastlane match appstore    # TestFlight / App Store

The generated Matchfile uses git storage, type("adhoc") by default, and read-only mode on CI. The iOS build lane accepts match_type: and the store lanes pass appstore for you.

Step 4: Run Flavor-Specific Builds

Lanes are per platform and take the flavor as an option (development, staging or production):

# Android - build a staging APK
bundle exec fastlane android build flavor:staging

# Android - per-ABI APKs
bundle exec fastlane android build flavor:staging split_per_abi:true

# iOS - build a staging IPA
bundle exec fastlane ios build flavor:staging

Each lane runs flutter build with --flavor <flavor> and the matching entry point (lib/main_development.dart, lib/main_staging.dart, lib/main.dart for production). Artifacts are named {AppName}-v{version}-{flavor}.{ext}.

Every lane's before_all calls dart run monorepo_toolkit build-prepare --flavor <flavor> with the build's own flavor: internal flavors keep the debug tooling, the production flavor gets the noop twins. flutter_build runs build-prepare --check-leaks after the build, and after_all/error restore the dependencies. See Build Prepare.

Step 5: Deploy

# Firebase App Distribution
bundle exec fastlane android distribute_firebase flavor:development
bundle exec fastlane ios distribute_firebase flavor:development
bundle exec fastlane distribute_all flavor:staging

# Stores
bundle exec fastlane android deploy_play_store flavor:production track:internal
bundle exec fastlane ios deploy_testflight flavor:production
bundle exec fastlane ios deploy_app_store flavor:production submit:true auto_release:true
bundle exec fastlane deploy_all flavor:production

Key Customization Points

Customization	Where to Change
App identifier and credentials	apps/<app_name>/fastlane/Appfile (or the env vars above)
Lane definitions	apps/<app_name>/fastlane/Fastfile
Signing certificate repo and type	apps/<app_name>/fastlane/Matchfile
Fastlane plugins	apps/<app_name>/fastlane/Pluginfile
Firebase tester group	groups: option (default qa-team)

Next Steps

• Set up GitHub Actions to run Fastlane lanes in CI
• Configure build_prepare to swap debug tooling out of production-flavor builds