Mobile CI/CD Boilerplate (GitHub Actions + Fastlane)

A minimal, opinionated starter for shipping iOS + Android apps with:

• Dev: TestFlight + Google Play Internal
• Prod: App Store + Google Play Production

This repo is intentionally lightweight. You plug in your own ios/ and android/ projects (React Native, native, etc.) and set the variables/secrets.

What’s included

• GitHub Actions workflows for dev and prod releases
• Fastlane lanes for iOS and Android
• Clear separation of dev vs prod tracks

Quick start

1. Add your mobile projects

   • Put your iOS project in ios/
   • Put your Android project in android/

2. Create the app entries in the stores

   • iOS: create the app in App Store Connect and ensure the bundle id matches IOS_APP_IDENTIFIER
   • Android: create the app in Google Play Console and ensure the package name matches ANDROID_PACKAGE_NAME

3. Make sure your iOS scheme is shared

   • In Xcode: Product > Scheme > Manage Schemes… and check Shared for the scheme you’ll build in CI

4. Set repo variables (non‑secret) in GitHub

   • IOS_WORKSPACE (e.g., ios/MyApp.xcworkspace) or IOS_PROJECT (e.g., ios/MyApp.xcodeproj)
   • IOS_SCHEME (e.g., MyApp)
   • IOS_APP_IDENTIFIER (e.g., com.example.app)
   • APPLE_TEAM_ID
   • ANDROID_PACKAGE_NAME (e.g., com.example.app)
   • ANDROID_PROJECT_DIR (optional; default: android)
   • ANDROID_GRADLE_TASK (optional; default: bundle)
   • ANDROID_BUILD_TYPE (optional; default: Release)
   • ANDROID_AAB_PATH (optional; default: android/app/build/outputs/bundle/release/app-release.aab)
   • MATCH_GCS_BUCKET (optional; GCS match backend)
   • MATCH_GCS_PROJECT_ID (optional; GCS match backend)
   • MATCH_S3_BUCKET (optional; S3 match backend)
   • MATCH_S3_REGION (optional; S3 match backend)
   • MATCH_S3_PREFIX (optional; S3 match backend)

5. Set repo secrets in GitHub

   • APP_STORE_CONNECT_API_KEY_ID
   • APP_STORE_CONNECT_API_ISSUER_ID
   • APP_STORE_CONNECT_API_KEY_CONTENT (base64-encoded .p8)
   • MATCH_GIT_URL (URL to your match repo)
   • MATCH_PASSWORD
   • MATCH_KEYCHAIN_PASSWORD (for CI temporary keychain)
   • PLAY_STORE_JSON_KEY (base64-encoded service account JSON)
   • MATCH_GCS_JSON_KEY (optional; raw GCS service account JSON)
   • AWS_ACCESS_KEY_ID (optional; S3)
   • AWS_SECRET_ACCESS_KEY (optional; S3)

6. Run a workflow

   • Dev: .github/workflows/dev.yml
   • Prod: .github/workflows/prod.yml

What you actually need to prepare

If you’re new to Fastlane, the two store credentials below are the only “non‑code” blockers:

• App Store Connect API key: Create an API key in App Store Connect. Store the .p8 content as base64 in APP_STORE_CONNECT_API_KEY_CONTENT, and the key/issuer IDs in APP_STORE_CONNECT_API_KEY_ID / APP_STORE_CONNECT_API_ISSUER_ID.
• Google Play service account: Create a service account in Google Cloud and grant it access in Play Console. Base64‑encode the JSON key into PLAY_STORE_JSON_KEY.

Common encoding examples (macOS):

base64 -i AuthKey_XXXX.p8
base64 -i play-service-account.json

First run checklist

1. Add ios/ and android/ projects and confirm paths in repo variables.
2. Create the app entries in App Store Connect and Google Play Console.
3. Share the iOS scheme in Xcode.
4. Configure Android release signing in your project.
5. Add all required repo variables and secrets.
6. Run .github/workflows/setup-signing.yml once (choose backend).
7. Trigger .github/workflows/dev.yml to validate TestFlight + Play Internal.

Workflow triggers

• Dev (.github/workflows/dev.yml)
  • Manual: workflow_dispatch
  • Auto: pushes to develop or dev
• Prod (.github/workflows/prod.yml)
  • Manual: workflow_dispatch
  • Auto: tag push matching v* (e.g., v1.2.3)

Signing setup (one-time)

Use the optional workflow below to bootstrap iOS signing on a fresh app. It runs fastlane match to create certificates and profiles, then stores them in your configured backend.

• Workflow: .github/workflows/setup-signing.yml
• Choose backend via the backend input when triggering (git, gcs, s3)
• Run once per app (or when rotating signing assets)
• After this, CI lanes use match in read‑only mode to fetch the assets

Storage backends

match supports multiple storage backends. Git is the default in this boilerplate, but you can use cloud storage too (e.g., Amazon S3 or Google Cloud Storage).

• Git (default): configure MATCH_GIT_URL and MATCH_PASSWORD
• Google Cloud Storage:
  • Set MATCH_GCS_BUCKET and MATCH_GCS_PROJECT_ID as repo variables
  • Add MATCH_GCS_JSON_KEY as a repo secret (service account JSON)
  • The workflow writes fastlane/gc_keys.json and uses fastlane/Matchfile.gcs
• Amazon S3:
  • Set MATCH_S3_BUCKET, MATCH_S3_REGION, and optional MATCH_S3_PREFIX as repo variables
  • Add AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as repo secrets
  • The workflow uses fastlane/Matchfile.s3

If you previously stored signing assets in Google Cloud Storage, keep that setup and wire the GCS service account key + bucket config into the workflow env. Fastlane supports alternate storage options; pick whichever fits your org.

When using GCS or S3, mirror the same storage config in your dev/prod workflows so match can fetch signing assets (copy the key-writing + Matchfile steps from the setup workflow).

Android signing note

This boilerplate assumes your Android project is already configured to sign Release builds (keystore + Gradle config). If your app isn’t signed yet, set up a keystore in your Android project before running the workflows.

Local usage

bundle install
bundle exec fastlane ios dev
bundle exec fastlane android dev

Create a local .env based on fastlane/.env.sample if you want to run locally.

Notes

• iOS signing is handled via match. Update fastlane/Fastfile if you prefer manual signing.
• One-time signing setup: if your repo includes a setup-signing.yml workflow, run it once to bootstrap certificates/profiles before the first CI release.
• App Store Connect auth expects a .p8 key at fastlane/AuthKey.p8 (CI creates it from the secret). For local runs, set APP_STORE_CONNECT_API_KEY_PATH.
• This repo assumes Release builds for Android.

File map

• fastlane/Fastfile – all lanes for dev/prod
• .github/workflows/dev.yml – dev pipeline
• .github/workflows/prod.yml – prod pipeline
• .github/workflows/setup-signing.yml – one-time iOS signing (choose backend)
• fastlane/.env.sample – local env template
• fastlane/Matchfile.gcs – match config template for GCS
• fastlane/Matchfile.s3 – match config template for S3

---

If you want me to tailor this for a specific app structure (e.g., monorepo, Expo, Flavors, multiple schemes), tell me your layout.