--- title: "Build Distribution" description: "Upload Android builds to Sentry for distribution to internal teams and beta testers." url: https://docs.sentry.io/platforms/android/build-distribution/ --- # Build Distribution | Sentry for Android [Build Distribution](https://docs.sentry.io/product/build-distribution.md) helps you securely distribute Android builds to your internal teams and beta testers. ## [Getting Started](https://docs.sentry.io/platforms/android/build-distribution.md#getting-started) **Accepted Formats**: APK (preferred) | AAB * **APK**: Distributed as uploaded. You must ensure uploaded APKs are properly signed and universal (if required) before uploading. Using a consistent signing key allows users to update previously installed builds. * **AAB (Android App Bundle)**: Build Distribution automatically converts AABs to universal APKs, but signs each upload with a unique key, which prevents users from updating previously installed builds. **Upload Mechanisms**: [Gradle](https://docs.sentry.io/platforms/android/build-distribution.md#uploading-with-gradle) | [Sentry CLI](https://docs.sentry.io/platforms/android/build-distribution.md#uploading-with-the-sentry-cli) ### [Uploading With Gradle](https://docs.sentry.io/platforms/android/build-distribution.md#uploading-with-gradle) The Gradle plugin automatically detects build metadata from your git repository. On GitHub Actions, all metadata is automatically detected. On other CI systems, you may need to manually set some values using the `vcsInfo` extension. 1. Configure the [Sentry Android Gradle plugin](https://docs.sentry.io/platforms/android/configuration/gradle.md) with at least version `6.12.0` 2. Set the auth token as an environment variable to be used when running your release build. ``` export SENTRY_AUTH_TOKEN= ``` 3. Enable uploading for distribution for CI builds. `build.gradle.kts` ``` sentry { distribution { enabled = providers.environmentVariable("GITHUB_ACTIONS").isPresent } } ``` Gradle-based uploads require the variant to not be excluded by the Sentry Gradle plugin's variant filters (`ignoredVariants`, `ignoredBuildTypes`, or `ignoredFlavors`). See [Variant Filtering](https://docs.sentry.io/platforms/android/configuration/gradle.md#variant-filtering) for details. 4. Invoke the following Gradle tasks to build your app and trigger the upload. `aab` ``` ./gradlew bundleRelease ``` 5. After an upload has successfully processed, confirm the metadata is correct in the Sentry UI ![Upload metadata](https://docs.sentry.io/_next/image/?url=%2Fplatforms%2Fandroid%2Fbuild-distribution%2Fimages%2Fandroid-metadata.png\&w=828\&q=75) ### Overriding Metadata The Gradle plugin automatically detects build metadata from your git repository. On GitHub Actions, all metadata is automatically detected. On other CI systems, you may need to manually set some values using the `vcsInfo` extension. Configure overrides in your Gradle build configuration: `build.gradle.kts` ``` sentry { distribution { enabled = providers.environmentVariable("GITHUB_ACTIONS").isPresent } vcsInfo { headSha.set("abc123") baseSha.set("def456") vcsProvider.set("github") headRepoName.set("organization/repository") baseRepoName.set("organization/repository") headRef.set("feature-branch") baseRef.set("main") prNumber.set(42) } } ``` Available `vcsInfo` properties: | Property | Type | Description | | -------------- | ------ | --------------------------------- | | `headSha` | String | Current commit SHA | | `baseSha` | String | Base commit SHA (for comparison) | | `vcsProvider` | String | VCS provider (e.g., "github") | | `headRepoName` | String | Repository name (org/repo format) | | `baseRepoName` | String | Base repository name | | `headRef` | String | Branch or tag name | | `baseRef` | String | Base branch name | | `prNumber` | Int | Pull request number | ### [Uploading With the Sentry CLI](https://docs.sentry.io/platforms/android/build-distribution.md#uploading-with-the-sentry-cli) 1. Install the [sentry-cli](https://docs.sentry.io/cli.md) (version `3.5.1`) We recommend using the latest version for the best possible experience, but at a minimum version `2.58.2` is required. 2. Authenticate the Sentry CLI by [following these steps](https://docs.sentry.io/cli/configuration.md#to-authenticate-manually) 3. Build your app to create an AAB (preferred) or APK 4. Invoke the following CLI command to trigger the upload: ```bash sentry-cli build upload app.aab \ --org your-org \ --project your-project \ --build-configuration Release ``` 5. After an upload has successfully processed, confirm the metadata is correct in the Sentry UI ## [Downloading Builds](https://docs.sentry.io/platforms/android/build-distribution.md#downloading-builds) Once builds are uploaded to Sentry, your team members and beta testers can download them through the Sentry web interface. 1. Open the URL printed to the console after uploading the build 2. Click the **Install** button on the right side of the page 3) Either scan the QR code from a mobile device or click the **Download** button to download the build directly After downloading, you can install the APK directly on your Android device. You'll need to enable installing apps from unknown sources: * **Android 8.0 and higher**: Navigate to the Install unknown apps system settings screen to enable app installations from your browser or file manager. * **Android 7.1.1 and lower**: Enable the Unknown sources setting in Settings > Security. For more information, see [Android's documentation on unknown sources](https://developer.android.com/distribute/marketing-tools/alternative-distribution#unknown-sources). ## [Upload Metadata](https://docs.sentry.io/platforms/android/build-distribution.md#upload-metadata) We use build metadata to organize builds in the UI and ensure correct comparisons. | Field | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `org`\* | Sentry organization slug | | `project`\* | Sentry project slug | | `build-configuration`\* | Build configuration describing how the app was built, for example `Release` or `Debug` or `Release-Bazel` | | `head-sha` | Current commit SHA | | `base-sha` | Base commit SHA (for comparisons, recommended to use the branch's merge-base) | | `vcs-provider` | VCS provider name (for example `github`, `gitlab`, `bitbucket`, `azure`, `github_enterprise`). If not provided, the provider will be auto-detected from the git remote URL. Note: Only `github` and `github_enterprise` are supported for status checks. | | `head-repo-name` | Repository name (`org/repo`) | | `pr-number` | Pull request number | | `head-ref` | Branch or tag name | | `base-ref` | Base branch name | | `install-group` | [Install group(s)](https://docs.sentry.io/product/build-distribution.md#install-groups) to control update visibility between builds. Can be specified multiple times | \* *required field* ### [Build Configuration](https://docs.sentry.io/platforms/android/build-distribution.md#build-configuration) Build configuration metadata keeps comparisons scoped to like-for-like builds. For example, on a PR status check, the comparison will only be made for builds with the same build configuration. This is important because `release` and `debug` builds can be drastically different in size due to compiler optimizations, minification (R8/ProGuard), and resource shrinking. Comparing a `debug` build against a `release` build would give misleading results. The Android Gradle plugin automatically sends the **build variant** as the build configuration. A build variant is the combination of a build type and product flavor: | Component | Examples | Description | | -------------- | ---------------------------------------------- | ---------------------------------------------------------- | | Build type | `debug`, `release` | Defines build settings like minification and debuggability | | Product flavor | `free`, `paid`, `demo` | Defines different versions of your app (optional) | | Build variant | `debug`, `release`, `freeDebug`, `paidRelease` | The combination of build type + flavor | For apps without product flavors, the build variant is just the build type (for example, `release`). For apps with flavors, it's the combination (for example, `freeRelease` or `paidDebug`). If your app flavors are comparable you may want to change the `build_configuration` to be set to the build type alone. * #### [Auto-Update SDK](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md) Enable automatic update checks and installations for internal Android builds using the Sentry Auto-Update SDK. * #### [Install Groups](https://docs.sentry.io/platforms/android/build-distribution/install-groups.md) Control which Android builds can see updates for each other using install groups. ## Pages in this section - [Auto-Update SDK](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md) - [Install Groups](https://docs.sentry.io/platforms/android/build-distribution/install-groups.md)