Build Distribution

Build Distribution helps you securely distribute Android builds to your internal teams and beta testers.

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 | Sentry CLI

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 with at least version 6.0.0-beta1

2. Set the auth token as an environment variable to be used when running your release build.

   Copied

   export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___

3. Enable uploading for distribution for CI builds.

   KotlinGroovy

   build.gradle.kts

   Copied

   sentry {
     distribution {
       enabled = providers.environmentVariable("GITHUB_ACTIONS").isPresent
     }
   }

4. Invoke the following Gradle tasks to build your app and trigger the upload.

   AabApk

   aab

   Copied

   ./gradlew bundleRelease

5. After an upload has successfully processed, confirm the metadata is correct in the Sentry UI

   

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:

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:

Uploading With the Sentry CLI

1. Install the sentry-cli (version 2.58.2)

   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

3. Build your app to create an AAB (preferred) or APK

4. Invoke the following CLI command to trigger the upload:

   Bash

   Copied

   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

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.

Upload Metadata

We use build metadata to organize builds in the UI and ensure correct comparisons.

* required field

Build Configuration

We use build metadata to organize builds in the UI and ensure correct comparisons.

* required field