Catch up on everthing we announced at this year's Firebase Summit. Learn more

Distribute iOS apps to testers using fastlane

You can distribute builds to testers using fastlane, an open source platform that automates building and releasing iOS and Android apps. It follows simple instructions defined in a Fastfile. After you set up fastlane and your Fastfile, you can integrate App Distribution with your fastlane configuration.

Step 1. Set up fastlane

  1. Install and set up fastlane.

  2. To add App Distribution to your fastlane configuration, run the following command from the root of your iOS project:

    fastlane add_plugin firebase_app_distribution

    If the command prompts you with an option, select Option 3:

Step 2. Authenticate with Firebase

Before you can use the Fastlane plugin, you must first authenticate with your Firebase project. There are three ways to achieve this:

Step 3. Set up your Fastfile and distribute your app

  1. In a ./fastlane/Fastfile lane, add a firebase_app_distribution block. Use the following parameters to configure the distribution:
    firebase_app_distribution parameters

    Required only if your app does not contain a Firebase config file (GoogleService-Info.plist): Your app's Firebase App ID. You can find the App ID in the Firebase console, on the General Settings page.

    app: "1:1234567890:ios:0a1b2c3d4e5f67890"

    The path to your GoogleService-Info.plist file, relative to the archived product path. Set to GoogleService-Info.plist by default.

    The file is used to get your app's Firebase App ID if the app parameter is unspecified.


    A refresh token that's printed when you run the plugin's login action (see Authenticate using a Google account, above), or when you authenticate your CI environment with the Firebase CLI (read Use the CLI with CI systems for more information).


    The path to your Google service account json file. See above for how to authenticate using service account credentials.


    Replaces apk_path (deprecated). Absolute path to the IPA file you want to upload. If unspecified, fastlane determines the file's location from the lane in which the file was generated.


    Release notes for this build.

    You can either specify the release notes directly:

    release_notes: "Text of release notes"

    Or, specify the path to a plain text file:

    release_notes_file: "/path/to/release-notes.txt"

    The email addresses of the testers you want to invite.

    You can specify the testers as a comma-separated list of email addresses:

    testers: ",,"

    Or, you can specify the path to a plain text file containing a comma-separated list of email addresses:

    testers_file: "/path/to/testers.txt"

    The tester groups you want to invite (refer to Manage testers). Groups are specified using group aliases, which you can look up in the Firebase console.

    You can specify the groups as a comma-separated list:

    groups: "qa-team, trusted-testers"

    Or, you can specify the path to a plain text file containing a comma-separated list of group names:

    groups_file: "/path/to/groups.txt"

    A boolean flag. You can set this to true to print verbose debug output.

For example:

platform :ios do
    desc "My awesome app"
    lane :distribute do
        # build_ios_app is a built-in fastlane action.

            app: "1:123456789:android:abcd1234",
            testers: ",",
            release_notes: "Lots of amazing new features to test out!"


Finally, to make the build available to testers, run your lane:

fastlane <lane>

Once you distribute your build, it becomes available in the App Distribution dashboard of the Firebase console for 150 days (five months). When the build is 30 days from expiring, an expiration notice appears in both the console and your tester's list of builds on their test device.

Testers who haven't been invited to test the app receive email invitations to get started, and existing testers receive email notifications that a new build is ready to test (read the tester set up guide for instructions on how to install the test app). You can monitor the status of each tester-whether they accepted the invitation and whether they downloaded the app-in the Firebase console.

Testers have 30 days to accept an invitation to test the app before it expires. When an invitation is 5 days from expiring, an expiration notice appears in the Firebase console next to the tester on a release. An invitation can be renewed by resending it using the drop-down menu on the tester row.

Step 4 (Optional). Managing testers for the distribution

You can add or remove testers from your app release by using your Fastfile file or by directly running fastlane actions. Running actions directly will override the values set in your Fastfile.

Once a tester has been added to your Firebase project, you can add them to individual releases. Testers who are removed will no longer have access to releases in your project, but may still retain access to your releases for a window of time.

Use Fastfile

# Use lanes to add or remove testers from an app release.
lane(:add_testers) do
    emails: ","
    # or file: "/path/to/testers.txt"

lane(:remove_testers) do
    emails: ","
    # or file: "/path/to/testers.txt"
# Add or remove testers with the terminal
$ fastlane add_testers
$ fastlane remove_testers

Run fastlane actions

fastlane run firebase_app_distribution_add_testers emails:","

fastlane run firebase_app_distribution_remove_testers emails:","

You can also specify testers using --file="/path/to/testers.txt instead of --emails.

The firebase_app_distribution_add_testers and firebase_app_distribution_remove_testers tasks also accept the following arguments:

  • project_name: Your Firebase project number.
  • service_credentials_file: The path to your Google service credentials file.
  • firebase_cli_token: Auth token for Firebase CLI.

The service_credentials_file and the firebase_cli_token are the same arguments used by the upload action.