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
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. There are three ways to achieve this:
-
Run the following command:
bundle exec fastlane run firebase_app_distribution_login
The command prints an authentication link. -
Open the link in a browser.
-
When prompted, sign in to your Google Account and grant permission to access your Firebase project. Copy the resulting code from the login browser and paste it into the command line. The login action then prints a refresh token, which the App Distribution plugin uses to authenticate with Firebase.
-
Pass the token from the previous step to the plugin, using either the
firebase_cli_token
parameter later when setting up your Fastfile, or by setting theFIREBASE_TOKEN
environment variable:export FIREBASE_TOKEN=token
Authenticating with a service account allows you to flexibly use the plugin with your continuous integration (CI) system. There are two ways to provide service account credentials:
- Pass your service account key file to the
firebase_app_distribution
action. You might find this method convenient if you already have your service account key file in your build environment. - Set the environment variable
GOOGLE_APPLICATION_CREDENTIALS
to point to your service account key file. You might prefer this method if you already have Application Default Credentials (ADC) configured for another Google service (e.g., Google Cloud).
- On the Google Cloud Console, select your project and create a new service account.
- Add the Firebase App Distribution Admin role.
- Create a private json key and move the key to a location accessible to your build environment. Be sure to keep this file somewhere safe, as it grants administrator access to App Distribution in your Firebase project.
- Skip this step if you created your app after September 20, 2019: In the Google APIs console, enable the Firebase App Distribution API. When prompted, select the project with the same name as your Firebase project.
Provide or locate your service account credentials:
- To pass your service account key to your lane's
firebase_app_distribution
action, set theservice_credentials_file
parameter with the path to your private key JSON file To locate your credentials with ADC, set the environment variable
GOOGLE_APPLICATION_CREDENTIALS
to the path for the private key JSON file. For example:export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/credentials/file.json
For more information on authenticating with ADC, read Providing credentials to your application.
- To pass your service account key to your lane's
See Log in with the Firebase CLI for instructions on how to authenticate your project.
Step 3. Set up your Fastfile and distribute your app
-
In a
./fastlane/Fastfile
lane, add afirebase_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 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).
service_credentials_file
The path to your Google service account json file. See above for how to authenticate using service account credentials.
apk_path
Absolute path to the APK 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"
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(...) # build_android_app is a built-in fastlane action. 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!" ) end end
-
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.