Distribute Android apps to testers using fastlane


This guide describes how to distribute AAB 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.

App Distribution integrates with Google Play’s internal app sharing service to process the AABs you upload and serve APKs that are optimized for your testers' device configurations. Distributing AABs lets you do the following:

  • Run optimized APKs (served by Google Play) that are optimized to your testers' devices.

  • Uncover and debug device-specific issues.

  • Test app bundle features like Play Feature Delivery and Play Asset Delivery.

  • Reduce the size of downloads for your testers.

Required permissions

To upload AABs to App Distribution, you must link your Firebase app to an app in Google Play. You must have the required level of access to perform these actions.

If you don't have the necessary Firebase access, you can ask a Firebase project Owner to assign you the applicable role via the Firebase console IAM settings. If you have questions about accessing your Firebase project, including finding or assigning an Owner, review the "Permissions and access to Firebase projects" FAQs.

The following table applies to linking a Firebase app to an app in Google Play, as well as uploading AABs.

Action in Firebase console Required IAM permission IAM role(s) that include required permissions by default Additional required role(s)
Link a Firebase app to an app in Google Play firebase.playLinks.update One of the following roles: Access to a Google Play developer account as Admin
Upload AABs to App Distribution firebaseappdistro.releases.update One of the following roles: ––

Before you begin

  1. If you haven't already, add Firebase to your Android project. At the end of this workflow, you'll have a Firebase Android App in your Firebase project.

    If you aren't using any other Firebase products, you only need to create a project and register your app. If you decide to use additional products, be sure to complete all of the steps in Add Firebase to your Android project.

  2. To create a Firebase link to Google Play and to upload AABs, make sure that your app meets the following requirements:

    • The app in Google Play and the Firebase Android app are both registered using the same package name.

    • The app in Google Play is set up on the app dashboard and is distributed to one of the Google Play tracks (Internal testing, Closed testing, Open testing, or Production).

    • The app's review in Google Play is complete and the app is published. Your app is published if the App status column displays one of the following statuses: Internal testing (not Draft internal testing), Closed testing, Open testing, or Production.

  3. Link your Firebase Android App to your Google Play developer account:

    1. In the Firebase console, go to your Project settings, then select the Integrations tab.

    2. On the Google Play card, click Link.
      If you already have links to Google Play, click Manage instead.

    3. Follow the on-screen instructions to enable the App Distribution integration and select which Firebase Android Apps to link to Google Play.

    Learn more about linking to Google Play.

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 Android project:

    fastlane add_plugin firebase_app_distribution

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

Step 2. Authenticate with Firebase

Before you can use the fastlane plugin, you must first authenticate with your Firebase project in one of the following ways. By default, the fastlane plugin looks for credentials from the Firebase CLI if no other authentication method is used.

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
    app

    Required: Your app's Firebase App ID. You can find the App ID in the Firebase console, on the General Settings page.

    app: "1:1234567890:android:0a1b2c3d4e5f67890"
    firebase_cli_token

    A refresh token that's printed when you authenticate your CI environment with the Firebase CLI (read Use the CLI with CI systems for more information).

    service_credentials_file

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

    android_artifact_type

    Specifies the Android file type (APK or AAB).

    android_artifact_path

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

    release_notes
    release_notes_file

    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"
    testers
    testers_file

    The email addresses of the testers you want to invite.

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

    testers: "ali@example.com, bri@example.com, cal@example.com"

    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"
    groups
    groups_file

    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"
    test_devices
    test_devices_file

    The following distribution types are part of the Automated tester beta feature.

    The test devices you want to distribute builds to (refer to Automated tests).

    You can specify the test devices as a semicolon-separated list of test devices:

    test_devices: "model=shiba,version=34,locale=en,orientation=portrait;model=b0q,version=33,locale=en,orientation=portrait"

    Or, you can specify the path to a plain text file containing a semicolon-separated list of test devices:

    test_devices_file: "/path/to/test-devices.txt"
    test_username

    The username for automatic login to be used during automated tests.

    test_password
    test_password_file

    The password for automatic login to be used during automated tests.

    Or, you can specify the path to a plain text file containing a password:

    test_password_file: "/path/to/test-password.txt"
    test_username_resource

    Resource name for the username field for automatic login to be used during automated tests.

    test_password_resource

    Resource name for the password field for automatic login to be used during automated tests.

    test_non_blocking

    Run automated tests asynchronously. Visit the Firebase console for the automatic test results.

    debug

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

platform :android do
    desc "My awesome app"
    lane :distribute do
        build_android_app(task: "bundle", ...)
        # build_android_app is a built-in fastlane action.
        release = firebase_app_distribution(
            app: "1:123456789:android:abcd1234",
            testers: "tester1@company.com, tester2@company.com",
            release_notes: "Lots of amazing new features to test out!",
            android_artifact_type: "AAB"
        )
    end
end

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

fastlane <lane>

The return value of the action is a hash representing the uploaded release. This hash is also available using lane_context[SharedValues::FIREBASE_APP_DISTRO_RELEASE]. For more information about the available fields in this hash, see the REST API documentation.

The fastlane plugin outputs the following links after the release upload. These links help you manage binaries and ensure that testers and other developers have the right release:

  • A link to the Firebase console displaying a single release. You can share this link with other developers in your org.
  • A link to the release in the tester experience (Android native app) that lets testers view release notes and install the app onto their device. The tester needs access to the release in order to use the link.
  • A signed link that directly downloads and installs the app binary (APK or AAB file). The link expires after one hour.

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

Testers who weren't previously invited to test the app receive email invitations to get started. Existing testers receive email notifications that a new build is ready to test. To learn how to install the test app, see tester set up guide. You can monitor the status of each tester to determine whether they accepted the invitation and whether they downloaded the app in the Firebase console.

(Optional) To automatically increment your build number every time you create a new release in App Distribution, you can use the firebase_app_distribution_get_latest_release action and, for example, the increment_version_code fastlane plugin. The following code provides an example of how to automatically increment your build number:

lane :increment_version do
  latest_release = firebase_app_distribution_get_latest_release(
    app: "<your Firebase app ID>"
  )
  increment_version_code({ version_code: latest_release[:buildVersion].to_i + 1 })
end

To learn more about the firebase_app_distribution_get_latest_release action, see Get information about your app's latest release.

Step 4 (Optional). Managing testers for the distribution

You can add and remove testers from your project or group using your Fastfile file or by directly running fastlane actions. Running actions directly overrides the values set in your Fastfile.

Once a tester is added to your Firebase project, you can add them to individual releases. Testers who are removed from your Firebase project no longer have access to releases in your project, but they might retain access to your releases for a window of time.

If you have a large number of testers you should consider using groups.

Use Fastfile

# Use lanes to add or remove testers from a project.
lane(:add_testers) do
  firebase_app_distribution_add_testers(
    emails: "foo@google.com,bar@google.com"
    # or file: "/path/to/testers.txt"
    group_alias: "qa-team" # (Optional) add testers to this group
  )
end

lane(:remove_testers) do
  firebase_app_distribution_remove_testers(
    emails: "foo@google.com,bar@google.com"
    # or file: "/path/to/testers.txt"
    group_alias: "qa-team" # (Optional) remove testers from this group only
  )
end
# Add or remove testers with the terminal
$ fastlane add_testers
$ fastlane remove_testers

Run fastlane actions

fastlane run firebase_app_distribution_create_group display_name:"QA Team" alias:"qa-team"
fastlane run firebase_app_distribution_add_testers group_alias:"qa-team" emails:"foo@google.com,bar@google.com"
fastlane run firebase_app_distribution_remove_testers group_alias:"qa-team" emails:"foo@google.com,bar@google.com"
fastlane run firebase_app_distribution_delete_group alias:"qa-team"

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.
  • group_alias (optional): If specified, the testers are added to (or removed from) specified group.
  • 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.

Step 5 (Optional). Get information about your app's latest release

You can use the firebase_app_distribution_get_latest_release action to fetch information about your app's latest release in App Distribution, including app version information, release notes, and creation time. Use cases include automatically increasing the version and carrying over the release notes from the previous release.

The return value of the action is a hash representing the latest release. This hash is also available using lane_context[SharedValues::FIREBASE_APP_DISTRO_LATEST_RELEASE]. For more information about the available fields in this hash, see the REST API documentation.

Parameters

firebase_app_distribution_get_latest_release parameters
app

Required: Your app's Firebase App ID. You can find the App ID in the Firebase console, on the General Settings page.

app: "1:1234567890:android:0a1b2c3d4e5f67890"
firebase_cli_token

A refresh token that's printed when you authenticate your CI environment with the Firebase CLI (read Use the CLI with CI systems for more information).

service_credentials_file

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

debug

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

Next steps