Stay organized with collectionsSave and categorize content based on your preferences.
This document describes how to distribute APK builds to testers usingfastlane,
an open source platform that automates building and releasing iOS and Android
apps. This document follows instructions defined in aFastfile. After you set
up fastlane and yourFastfile, you can integrateApp Distributionwith your
fastlane configuration.
If you aren't using any other Firebase products, you only have to create a
project and register your app. However, if you decide to use additional
products in the future, be sure to complete all of the steps on the page
linked above.
To addApp Distributionto 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, selectOption 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 theFirebaseCLI if no other authentication
method is used.
Use Firebase service account credentials
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 thefirebase_app_distributionaction. You might find this method convenient if you already have your
service account key file in your build environment.
Set the environment variableGOOGLE_APPLICATION_CREDENTIALSto point to
your service account key file. You might prefer this method if you
already haveApplication Default Credentials (ADC)configured for another Google service (e.g.,Google Cloud).
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 toApp Distributionin your Firebase project.
Skip this step if you created your app after September 20,
2019: In the Google APIs console, enable theFirebase App DistributionAPI.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'sfirebase_app_distributionaction, set theservice_credentials_fileparameter with the path to your private key JSON file
To locate your credentials with ADC, set the environment variableGOOGLE_APPLICATION_CREDENTIALSto the path for the private key JSON
file. For example:
Replacesapk_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:
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 duringautomated tests.
test_password test_password_file
The password for automatic login to be used duringautomated 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 duringautomated tests.
test_password_resource
Resource name for the password field for automatic login to be used duringautomated tests.
test_non_blocking
Runautomated testsasynchronously. Visit the Firebase console for the automatic test results.
debug
A boolean flag. You can set this totrueto print verbose debug output.
platform :android do
desc "My awesome app"
lane :distribute do
build_android_app(...)
# build_android_app is a built-infastlane 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!"
)
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 usinglane_context[SharedValues::FIREBASE_APP_DISTRO_RELEASE].
For more information about the available fields in this hash, see theREST 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 theFirebaseconsole 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 theApp Distributiondashboard of theFirebaseconsole 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,
seetester 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 theFirebaseconsole.
Step 4 (Optional). Managing testers for the distribution
You can add and remove testers from your project or group using yourFastfilefile or by directly running fastlane actions. Running actions directly
overrides the values set in yourFastfile.
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.
UseFastfile
# 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.txtinstead of--emails.
Thefirebase_app_distribution_add_testersandfirebase_app_distribution_remove_testerstasks 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 forFirebaseCLI.
Theservice_credentials_fileand thefirebase_cli_tokenare the same
arguments used by the upload action.
Step 5 (Optional). Get information about your app's latest release
You can use thefirebase_app_distribution_get_latest_releaseaction
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 usinglane_context[SharedValues::FIREBASE_APP_DISTRO_LATEST_RELEASE].
For more information about the available fields in this hash, see theREST API documentation.
