Distribute Android apps to testers using Gradle

You can integrate App Distribution into your Android build process using the App Distribution Gradle plugin. The plugin lets you specify your testers and release notes in your app's build.gradle file, letting you configure distributions for different build types and variants of your app.

Before you begin

If you haven't already, add Firebase to your Android project.

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.

1. Set up your Android project

In your module (app-level) Gradle file (usually app/build.gradle), include the App Distribution plugin below the Android plugin:

apply plugin: 'com.android.application'
// ...

apply plugin: 'com.google.firebase.appdistribution'
// ...

buildscript {
    repositories {
        google()
    }
    dependencies {
        classpath 'com.google.firebase:firebase-appdistribution-gradle:1.1.0'
    }
}

2. Authenticate with Firebase

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

• Sign in to your Google Account via the Gradle plugin
• Use Firebase service account credentials
• Sign in to Firebase using the Firebase CLI

Authenticate using your Google Account

1. Run the following command:

   ./gradlew appDistributionLogin
   

   The command prints an authentication link.

2. Open the link in a browser.

3. When prompted, sign in to your Google Account and grant permission to access your Firebase project. The Gradle command prints a refresh token, which the App Distribution plugin uses to authenticate with Firebase.

4. Set the environment variable FIREBASE_TOKEN to the token from the previous step:

   export FIREBASE_TOKEN=<token>
   

Authenticate using a service account

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 build.gradle. 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 ADC configured for another Google service (e.g., Google Cloud Platform).

To authenticate using service account credentials:

1. On the Google Cloud Platform console, select your project and create a new service account.
2. Add the Firebase Quality Admin role.
3. 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 your Firebase project.
4. 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.

5. Provide or locate your service account credentials:

   1. To pass Gradle your service account key, in your build.gradle file, set the property serviceCredentialsFile to the private key JSON file.

   2. To locate your credentials with ADC, set the environment variable GOOGLE_APPLICATION_CREDENTIALS. Replace [PATH] with the path of the private key JSON file and [FILE_NAME] with the filename. 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.

3. Configure your distribution properties

1. In your app/build.gradle file, configure App Distribution by adding at least one firebaseAppDistribution section. You can configure App Distribution for both build types and product flavors. For example, to distribute the release build to testers:

   android {
   
       // ...
   
       buildTypes {
           release {
               firebaseAppDistribution {
                   releaseNotesFile="/path/to/releasenotes.txt"
                   testers="ali@example.com, bri@example.com, cal@example.com"
               }
           }
       }
   
       // ...
   }
   

   And to distribute debug and release builds in "demo" and "full" product flavors:

   android {
   
       // ...
   
       buildTypes {
           debug {...}
           release {...}
       }
   
       flavorDimensions "version"
       productFlavors {
         demo {
             dimension "version"
             firebaseAppDistribution {
                 releaseNotes="Release notes for demo version"
                 testers="demo@testers.com"
             }
         }
         full {
             dimension "version"
             firebaseAppDistribution {
                 releaseNotes="Release notes for full version"
                 testers="full@testers.com"
             }
         }
       }
   
       // ...
   }
   

Use the following parameters to configure App Distribution:

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

testersFile="/path/to/testers.txt"

groups="qa-team, android-testers"

groupsFile="/path/to/tester-groups.txt"

4. Distribute your app to testers

Finally, to package your test app and invite testers, build the targets assembleBUILD-VARIANT and appDistributionUploadBUILD-VARIANT with your project's Gradle wrapper, where BUILD-VARIANT is the optional product flavor and build type you configured in the previous step.

For example, to distribute your app using the release build variant, run the following command:

./gradlew assembleRelease appDistributionUploadRelease

Or, if you authenticated with your Google Account and didn't provide credentials in your Gradle build file, include the FIREBASE_TOKEN variable:

export FIREBASE_TOKEN=1/a1b2c3d4e5f67890
./gradlew --stop // Only needed for environment variable changes
./gradlew assembleRelease appDistributionUploadRelease

Testers who haven't been invited to test the app receive email invitations to get started. Existing testers receive email notifications that a new build is ready to test.

For more information about product flavors, see Configure build variants.