skip to content

In Firebase App Distribution, how does CI upload a nightly Android build to tester groups with release notes, via the CLI or Gradle plugin?

level: middleimportance: should knowfreq 30%

answer

  1. two upload paths from CI
  2. Firebase App ID, not package name
  3. groups by alias, not display name
  4. service account, Admin role
  5. appDistributionUpload plus the variant

basics

~10 s

CI runs firebase appdistribution:distribute with --app, --groups and --release-notes-file, or the Gradle plugin's appDistributionUploadRelease task configured in a firebaseAppDistribution block, both authenticated with a service account holding the Firebase App Distribution Admin role.

solid answer

~40 s

Two paths do the same job. The **Firebase CLI** runs `firebase appdistribution:distribute app-release.apk --app <Firebase App ID> --groups "qa-team, product" --release-notes-file notes.txt`. The **App Distribution Gradle plugin** (`com.google.firebase.appdistribution`, 5.3.0) puts a `firebaseAppDistribution { artifactType; groups; releaseNotesFile }` block in a build type or flavor, and CI runs `./gradlew assembleRelease appDistributionUploadRelease`. Groups are named by **alias**, testers by email. For auth, CI uses a service account with the **Firebase App Distribution Admin** role, through `GOOGLE_APPLICATION_CREDENTIALS` or the plugin's `serviceCredentialsFile`; the `--token` and `FIREBASE_TOKEN` route is deprecated in the current CLI. Groups beat listing emails because group membership grants access to every release sent to that group.

code

kotlin · 22 lines
kotlin
// app/build.gradle.kts (excerpt)
import com.google.firebase.appdistribution.gradle.firebaseAppDistribution

plugins {
    id("com.android.application")
    id("com.google.gms.google-services")
    id("com.google.firebase.appdistribution")
}

android {
    // ...
    buildTypes {
        getByName("release") {
            firebaseAppDistribution {
                artifactType = "APK"
                groups = "qa-team, product"
                releaseNotesFile = "/ci/release-notes.txt"
                serviceCredentialsFile = "/secrets/appdist-ci.json"
            }
        }
    }
}

go deeper

for a junior

Know that the Firebase CLI and the Gradle plugin both upload a build, attach release notes and name testers or groups, so nobody drags files into the console.

for a middle

Explain the moving parts: the Firebase App ID for --app, group aliases, release notes from a file, the per-variant firebaseAppDistribution block and the appDistributionUpload task.

for a senior

Show how you run it safely in CI: a service account key kept as a secret, the deprecated token path retired, and groups managed once rather than emails hard-coded per job.

for a principal

Decide which builds and audiences the pipeline publishes automatically, who owns group membership, and how many testers each group may hold within the project limits.

## Two upload paths, one result A nightly job ends with a signed binary and has to turn it into an App Distribution **release**: upload it, attach **release notes**, and grant access to **testers** (by email) or **groups** (by alias). Firebase gives Android teams two scripted ways to do that, besides dragging a file into the console: | | Firebase CLI | App Distribution Gradle plugin | |---|---|---| | Entry point | `firebase appdistribution:distribute <file>` | `appDistributionUpload<Variant>` task | | App identity | `--app` (required) | `appId`, or read from `google-services.json` by the Google services plugin | | Testers / groups | `--testers`, `--groups` (or `-file` forms) | `testers`, `groups` (or `testersFile`, `groupsFile`) | | Release notes | `--release-notes` or `--release-notes-file` | `releaseNotes` or `releaseNotesFile` | | Artifact | file extension: `.apk`, `.aab` or `.ipa` | `artifactType = "APK"` or `"AAB"`, optional `artifactPath` | | Per-variant config | one command per binary | a block per build type or product flavor | The CLI suits a pipeline that already has the file and may also ship iOS, since the same command uploads an IPA. The plugin suits an Android build where each variant, say a `staging` flavor for QA and a `demo` flavor for clients, has its own testers and notes. ## The CLI path - `--app` takes the **Firebase App ID** (shape `1:<project number>:android:<hex>`, from the console's General settings), not the package name. Without it the CLI stops with "set the --app option to a valid Firebase app id and try again". - `--groups "qa-team, product"` names groups by their **alias**, which you see in the console or set when creating one with `firebase appdistribution:groups:create "QA team" qa-team`. - `--release-notes` turns a literal `\n` into a newline; `--release-notes-file` reads a text file, the usual choice for notes generated from commit messages. - After the upload the CLI says whether it created a new release, updated an existing one, or re-uploaded a binary it already had, and prints three links: the console page for the release, the tester-facing link, and a signed binary download link that **expires after one hour**. ## The Gradle plugin path 1. Add `id("com.google.firebase.appdistribution") version "5.3.0" apply false` in the root build file and apply it in the app module next to the Google services plugin. 2. Configure a `firebaseAppDistribution { }` block inside a build type or product flavor. The Kotlin DSL needs plugin 3.1.0 or later and the import `com.google.firebase.appdistribution.gradle.firebaseAppDistribution`. 3. Run the build and the upload in one invocation: `./gradlew assembleRelease appDistributionUploadRelease` for an APK, or `bundleRelease` with `artifactType = "AAB"` for a bundle. Any property can be overridden on the command line as `--<property>=<value>`, and the plugin adds `appDistributionAddTesters` and `appDistributionRemoveTesters` tasks for managing the tester list. ## Authenticating a CI runner - **Service account (recommended).** Create one in the Google Cloud console with the **Firebase App Distribution Admin** role and a JSON key. Point `GOOGLE_APPLICATION_CREDENTIALS` at the key (both tools read it), or set the plugin's `serviceCredentialsFile`. Treat the key as a secret: it grants administrator access to App Distribution in the project. - **Refresh token (legacy).** `firebase login:ci` prints a token used as `--token` or `FIREBASE_TOKEN`. The plugin docs still show it, but Firebase CLI 15.33.0 warns that `login:ci`, `--token` and `FIREBASE_TOKEN` are deprecated and will be removed in a future major version, and points to a service account instead. ## Why groups, not email lists A **group** is more than a mailing list. Adding a tester to a group gives them access to **every release already distributed to that group**; removing them takes away the releases they could reach only through it, while access granted by another group stays. So the nightly job names the same groups every night and membership is managed once in the console. Limits apply: 500 testers per project and 200 per group, raised at no cost on request. ```console $ export GOOGLE_APPLICATION_CREDENTIALS=/secrets/appdist-ci.json $ firebase appdistribution:distribute app/build/outputs/apk/release/app-release.apk \ --app 1:1234567890:android:0a1b2c3d4e5f67890 \ --groups "qa-team, product" \ --release-notes-file build/release-notes.txt ``` Existing testers get a new-build email; anyone never invited gets an invitation first.

  • A product manager joins the product group in Firebase App Distribution mid-sprint; which builds can they install?
    Every release already distributed to that group, not only the next one. Group membership is evaluated against the releases sent to the group, so adding someone grants the back catalogue that has not expired, and removing them revokes the releases they could reach only through that group. That is why a nightly job should target stable group aliases instead of hard-coded email lists.
  • Your CI job uses FIREBASE_TOKEN for Firebase App Distribution uploads; why change it?
    Firebase CLI 15.33.0 warns that authenticating with `--token`, `FIREBASE_TOKEN` or a `login:ci` token is deprecated and will be removed in a future major version. The token also belongs to a person's Google Account. A service account with the Firebase App Distribution Admin role, supplied through `GOOGLE_APPLICATION_CREDENTIALS` or the Gradle plugin's `serviceCredentialsFile`, is scoped to the project and survives people leaving.

  • The --app flag takes the app's package name.
  • Groups are passed by their display name, such as QA team.
  • The appDistributionUploadRelease task builds a fresh APK by itself.
  • A login:ci token is the recommended way to authenticate CI.
  • Adding a tester to a group only affects future releases.

Assumes Firebase CLI 15.33.0 and App Distribution Gradle plugin 5.3.0; the plugin's Kotlin DSL needs 3.1.0+, and the CLI now warns that --token, FIREBASE_TOKEN and login:ci are deprecated.