Production-Style Mobile CI/CD for React Native with CircleCI, Fastlane and White-Label Apps

Shipping a mobile app once is easy.

Shipping it every day, to multiple environments (QA, staging, production), for two platforms (iOS + Android), and then duplicating it as a white-label app for a customer — that’s where things get ugly quickly.

In this post I’ll walk through a production-style CI/CD setup for a React Native app that solves exactly that:

• CircleCI for pipelines
• Fastlane for iOS/Android automation
• Firebase App Distribution for betas
• Play Store / App Store for production
• A white-label flow that reuses the same codebase and pipeline

This article is based on the demo repo I used for a conference talk. The examples are simplified, but the patterns are real and ready to adapt to your own project.

🎥 If you prefer video first: this post follows the same ideas I show in my talk: YouTube GithubRepo

1. The Problem We’re Solving

We want to support:

1. Multiple environments

   • qa, staging, production

2. Two platforms

   • Android (Gradle)
   • iOS (Xcode)

3. Two distributions per platform

   • Beta → Firebase App Distribution
   • Production → Google Play / App Store & TestFlight

4. White-labeling

   • A second branded app, with different bundle IDs, signing, icons, etc.
   • Still built from the same repository and pipeline

The goal: one CI/CD pipeline that handles all of this with minimal duplication and predictable behavior.

2. High-Level Architecture

Here’s the big picture: a developer push kicks off CI, which runs tests and fans out into platform-specific Fastlane lanes that take care of distribution.

  flowchart TD
  Dev["Developer pushes to Git"] --> CI["CircleCI workflow"]
  CI --> Tests["JS tests (Jest, etc.)"]
  Tests --> BuildAndroid["Fastlane: Android lane"]
  Tests --> BuildIOS["Fastlane: iOS lane"]

  BuildAndroid --> BetaAndroid["Firebase App Distribution (Android)"]
  BuildIOS --> BetaIOS["Firebase App Distribution (iOS)"]

  BuildAndroid --> PlayStore["Google Play (internal / production)"]
  BuildIOS --> AppStore["App Store / TestFlight"]

  subgraph WhiteLabel["White-label apps"]
    BuildAndroid --> WLPlay["White-label app on Google Play"]
    BuildIOS --> WLStore["White-label app on App Store"]
  end

The important part: white-label apps are not special in the pipeline. They are just another build profile with its own identifiers and signing.

3. Repository Layout (Conceptual)

You don’t need anything exotic in your repo. A typical structure looks like this:

.
├── android/
│   ├── app/
│   │   └── build.gradle      # productFlavors, signingConfigs
│   └── keystores/
│       └── README.md         # how to generate & use keystores
├── ios/
│   └── Product.xcworkspace   # Xcode workspace / project
├── fastlane/
│   ├── Fastfile              # main lanes
│   ├── Matchfile             # certificate / profile config
│   └── helpers/
│       └── CompanyFastlane.rb  # build profiles (QA/Staging/Prod/WhiteLabel)
├── .circleci/
│   └── config.yml            # CI workflows
└── docs/
    └── README.md             # extra notes & links

Three main layers work together:

• Platform configs (android/, ios/)
• Build logic (Fastlane + helper Ruby classes)
• Pipelines (CircleCI workflows)

4. Step 1 – Define Environments and Flavors

4.1 Android: productFlavors

Android flavors let us create multiple “apps” from the same module.

android {
    // ...

    productFlavors {
        production {
            dimension "version"
            signingConfig signingConfigs.release
            resValue "string", "app_name", "Product"
        }

        qa {
            dimension "version"
            signingConfig signingConfigs.release
            applicationIdSuffix ".qa"
            resValue "string", "app_name", "Product QA"
        }

        staging {
            dimension "version"
            signingConfig signingConfigs.release
            applicationIdSuffix ".staging"
            resValue "string", "app_name", "Product Staging"
        }

        // White-label example
        WhiteLabelCustomer {
            dimension "version"
            signingConfig signingConfigs.release_branded
            applicationId "com.whitelabel.customer"
            resValue "string", "app_name", "WhiteLabel Customer"
        }
    }
}

Key ideas:

• Each flavor has its own applicationId (important for Play Store and Firebase).
• Each flavor can use a different signingConfig (separate keystore for the white-label).
• We reuse the same code, but generate different apps.

4.2 iOS: Schemes & Bundle IDs

On iOS, we usually combine:

• Schemes (Product.qa, Product.staging, Product, WhiteLabelCustomer)
• Bundle identifiers (com.company.Product.qa, com.whitelabel.customer, …)

To avoid hardcoding that in multiple places, I like to keep it in a Ruby helper used by Fastlane:

class CompanyFastlane
  XCODEPROJECT   = 'ios/Product.xcodeproj'
  XCODEWORKSPACE = 'ios/Product.xcworkspace'

  class BuildsInternal < CompanyFastlane
    class Qa < BuildsInternal
      BUNDLEID           = 'com.company.Product.qa'
      GOOGLESERVICEPLIST = 'GoogleService.qa-Info.plist'
      XCODESCHEME        = 'Product.qa'
    end

    class Production < BuildsInternal
      BUNDLEID           = 'com.company.Product'
      GOOGLESERVICEPLIST = 'GoogleService.release-Info.plist'
      XCODESCHEME        = 'Product'
    end
  end

  class BuildsWhiteLabel < CompanyFastlane
    GYMEXPORTMETHOD = 'app-store'
    MATCHTYPE       = 'appstore'

    class WhiteLabelCustomer < BuildsWhiteLabel
      BUNDLEID           = 'com.whitelabel.customer'
      GOOGLESERVICEPLIST = 'GoogleService.WhiteLabelCustomer-Info.plist'
      XCODESCHEME        = 'WhiteLabelCustomer'
      MATCHGITBRANCH     = 'WhiteLabelCustomer'
    end
  end
end

This gives us a single source of truth for:

• Bundle IDs
• Schemes
• Firebase configs
• Match branches / export methods

5. Step 2 – Model Builds in Fastlane

Now that flavors & schemes exist, we need Fastlane lanes that know how to build and ship each environment.

We use:

• Public lanes (entry points) e.g. android firebase_qa
• Private lanes to share behavior, e.g. common_build, distribution_firebase

5.1 Android lanes

Conceptually:

platform :android do
  before_all do
    ensure_env_vars(env_vars: ['FIREBASE_CLI_TOKEN'])
    sh "./helpers/beta_msg.sh > helpers/beta_msg_placeholder.txt"
  end

  desc "QA beta build → Firebase"
  lane :firebase_qa do
    common_build(customer: CompanyFastlane::BuildsInternal::Qa)
    distribution_firebase(customer: CompanyFastlane::BuildsInternal::Qa)
  end

  desc "Production build → Play Store"
  lane :release do
    common_build(customer: CompanyFastlane::BuildsInternal::Production)
    distribution_playmarket(customer: CompanyFastlane::BuildsInternal::Production)
  end

  desc "White-label production build → Play Store"
  lane :whitelabel_WhiteLabelCustomer do
    common_build(customer: CompanyFastlane::BuildsWhiteLabel::WhiteLabelCustomer)
    distribution_playmarket(customer: CompanyFastlane::BuildsWhiteLabel::WhiteLabelCustomer)
  end
end

5.2 iOS lanes

Symmetric to Android:

platform :ios do
  desc "QA beta build → Firebase App Distribution"
  lane :firebase_qa do
    common_build(customer: CompanyFastlane::BuildsInternal::Qa)
    distribution_firebase(customer: CompanyFastlane::BuildsInternal::Qa)
  end

  desc "Production build → TestFlight / App Store"
  lane :release do
    common_build(customer: CompanyFastlane::BuildsInternal::Production)
    distribution_testflight(customer: CompanyFastlane::BuildsInternal::Production)
  end

  desc "White-label production build → TestFlight / App Store"
  lane :whitelabel_WhiteLabelCustomer do
    common_build(customer: CompanyFastlane::BuildsWhiteLabel::WhiteLabelCustomer)
    distribution_testflight(customer: CompanyFastlane::BuildsWhiteLabel::WhiteLabelCustomer)
  end
end

The beauty: white-label is “just another customer” for the same private lanes.

6. Step 3 – CircleCI Workflows (Beta + Production)

CircleCI glues everything together and decides when to run which lane.

We usually have two workflows:

1. deploy_beta – for feature branches / internal builds
2. deploy_production – for integration / main branches

6.1 Overview of workflows

  flowchart TD
  subgraph BetaWorkflow["deploy_beta"]
    A["Push to non-main branch"] --> NodeBeta["nodejs_setup (tests)"]
    NodeBeta --> QAApprove["approve_beta_qa (manual)"]
    NodeBeta --> StagingApprove["approve_beta_staging (manual)"]

    QAApprove --> AndroidBetaQA["android_beta_qa"]
    QAApprove --> IOSBetaQA["ios_beta_qa"]

    StagingApprove --> AndroidBetaStaging["android_beta_staging"]
    StagingApprove --> IOSBetaStaging["ios_beta_staging"]
  end

  subgraph ProductionWorkflow["deploy_production"]
    B["Push to integration / main"] --> NodeProd["nodejs_setup (tests)"]
    NodeProd --> AndroidApprove["android_approve (manual)"]
    NodeProd --> IOSApprove["ios_approve (manual)"]

    AndroidApprove --> AndroidDeploy["android_deploy"]
    AndroidApprove --> AndroidDeployWL["android_deploy_WhiteLabelCustomer"]

    IOSApprove --> IOSDeploy["ios_deploy"]
    IOSApprove --> IOSDeployWL["ios_deploy_WhiteLabelCustomer"]
  end

Each CircleCI job is basically:

android_deploy:
  <<: *android_flow_deploy
  environment:
    FASTLANE_LANE: "android release"

android_deploy_WhiteLabelCustomer:
  <<: *android_flow_deploy
  environment:
    FASTLANE_LANE: "android whitelabel_WhiteLabelCustomer"

ios_deploy:
  <<: *ios_flow_deploy
  environment:
    FASTLANE_LANE: "ios release"

ios_deploy_WhiteLabelCustomer:
  <<: *ios_flow_deploy
  environment:
    FASTLANE_LANE: "ios whitelabel_WhiteLabelCustomer"

The job itself simply runs something like:

bundle exec fastlane $FASTLANE_LANE

CircleCI doesn’t need to know about bundle IDs, schemes or environments — that’s all encapsulated in Fastlane.

7. Step 4 – Beta Distribution with Firebase App Distribution

For beta builds we want:

• Quick feedback from QA / stakeholders
• Automatic release notes
• Traceability back to commits / PRs

A typical beta lane will:

1. Build the app for the correct flavor/scheme
2. Generate release notes (via a small shell script)
3. Upload to Firebase with firebase_app_distribution

Conceptually:

lane :distribution_firebase do |options|
  app_id = options[:customer]::ANDROID_FIREBASE_APP_QA # or environment-specific

  firebase_app_distribution(
    app: app_id,
    testers: "qa-team@example.com",
    release_notes_file: options[:customer]::FIREBASERELEASENOTESFILE
  )
end

The release notes script can pull:

• Branch name
• Build number
• PR URL
• CircleCI build URL
• Last commit message

8. Step 5 – Production Distribution: Play Store & App Store

Production lanes are almost the same, but:

• On Android we push to a track (internal, beta, or production)
• On iOS we upload to TestFlight and optionally promote to the App Store

8.1 Android → Google Play

Using supply (or upload_to_play_store):

lane :distribution_playmarket do |options|
  supply(
    package_name: options[:customer]::BUNDLEID,
    track: 'internal',
    skip_upload_screenshots: true,
    skip_upload_images: true
  )
end

8.2 iOS → TestFlight / App Store

Using gym + pilot:

lane :distribution_testflight do |options|
  gym(
    scheme: options[:customer]::XCODESCHEME,
    export_method: options[:customer]::GYMEXPORTMETHOD
  )

  pilot(
    app_identifier: options[:customer]::BUNDLEID,
    distribute_external: false
  )
end

For white-label customers we often use a separate Match branch and app-store export method, which is exactly what BuildsWhiteLabel::WhiteLabelCustomer controls.

9. Step 6 – White-Labeling: Concept and Shape

Let’s zoom in on the white-label aspect.

We want:

• Single codebase
• Multiple branded apps
• Single CI/CD pipeline

Conceptually:

  flowchart LR
  Code["Shared React Native codebase"] --> CoreApp["Core product app"]
  Code --> WLApp["White-label customer app"]

  CoreApp --> CoreBeta["Core – Firebase beta"]
  CoreApp --> CoreStores["Core – stores"]

  WLApp --> WLBeta["White-label – Firebase beta"]
  WLApp --> WLStores["White-label – stores"]

  subgraph Config["Configuration layer"]
    Flavors["Android flavors"]
    Schemes["iOS schemes"]
    Profiles["Fastlane profiles"]
    CIJobs["CircleCI jobs"]
  end

  Flavors --> CoreApp
  Flavors --> WLApp
  Schemes --> CoreApp
  Schemes --> WLApp
  Profiles --> CoreApp
  Profiles --> WLApp
  CIJobs --> CoreApp
  CIJobs --> WLApp

In practice, adding a new white-label app means:

1. Android – add a productFlavor with:

   • New applicationId
   • New signingConfig
   • Brand resources (name, icon, colors)

2. iOS – add:

   • Xcode scheme
   • Bundle ID
   • GoogleService.<Customer>-Info.plist if needed

3. Fastlane – create a new profile class under BuildsWhiteLabel with:

   • BUNDLEID, XCODESCHEME, GOOGLESERVICEPLIST, MATCHGITBRANCH, etc.

4. CircleCI – add jobs that point to:

   • android whitelabel_NewCustomer
   • ios whitelabel_NewCustomer

And you’re done. No extra “pipeline per customer”, just new configuration plugged into the same pipeline.

10. Local Usage & Example Commands

All of this is still convenient to run locally for debugging:

# Install Ruby deps
bundle install

# Install JS deps
yarn install

# Android QA beta → Firebase
bundle exec fastlane android firebase_qa

# Android production → Play Store
bundle exec fastlane android release

# Android white-label production
bundle exec fastlane android whitelabel_WhiteLabelCustomer

# iOS QA beta → Firebase
bundle exec fastlane ios firebase_qa

# iOS production → TestFlight
bundle exec fastlane ios release

# iOS white-label production
bundle exec fastlane ios whitelabel_WhiteLabelCustomer

11. Takeaways

A few key patterns I’d highlight:

• Separate “what to build” from “how to build”

  • Environments & brands live in flavors/schemes and Ruby profile classes.
  • Lanes and CI jobs stay generic.

• Let Fastlane own the complexity

  • CircleCI only needs to know which lane to call.

• White-label apps are config, not forks

  • New customer? Add a profile + flavor + scheme + jobs.
  • Same code, same pipeline, different branding & signing.

If you already have a React Native app and some Fastlane in place, you don’t have to adopt everything at once. Start with:

1. Android/iOS flavors/schemes for qa and production.
2. A single firebase_qa lane for each platform.
3. Later: add production, then white-label customers as needed.

If you’d like, I can also share a minimal starter Fastfile and config.yml that you can drop into a fresh project and evolve from there.