---
title: "Auto-Update SDK"
description: "Enable automatic update checks and installations for internal Android builds using the Sentry Auto-Update SDK."
url: https://docs.sentry.io/platforms/android/build-distribution/auto-update/
---

# Auto-Update SDK | Sentry for Android

This feature is available only if you're in the [Early Adopter program](https://docs.sentry.io/organization/early-adopter-features.md). Features available to Early Adopters are still in-progress and may have bugs. We recognize the irony.

The Auto-Update SDK is designed for **internal builds only** and should never be used in production builds distributed through the Google Play Store or other public app stores.

The Sentry Auto-Update SDK enables your internal Android builds to automatically check for and install newer versions distributed through Sentry's Build Distribution. This is particularly useful for distributing nightly, alpha, or beta builds to your internal teams.

## [Pre-requisites](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#pre-requisites)

Make sure your Sentry Java version is at least 8.27.0 and you have the [Sentry Android Gradle Plugin](https://docs.sentry.io/platforms/android/configuration/gradle.md) configured for your project.

You'll also need an [internal integration token](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#create-an-integration-token) with Build Distribution permissions.

## [Create an Integration Token](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#create-an-integration-token)

To use the Auto-Update SDK, you need to create an internal integration token with the appropriate permissions:

1. Navigate to **Settings > Custom Integrations** in your Sentry organization

2. Click **Create New Integration**

3. Select **Internal Integration** and click **Next**

4. Give your integration a name (e.g., "Build Distribution")

5. Under **Permissions**, select **Read** next to the **Distribution** scope.

6. Click **Save Changes**

7. Scroll down to the Tokens section and click **New Token**

8. Save the generated token, you'll need it to integrate the SDK

## [Installation](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#installation)

### [Configure the Gradle Plugin](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#configure-the-gradle-plugin)

Add the auto-update SDK configuration to your app's `build.gradle` or `build.gradle.kts` file:

`build.gradle.kts`

```kotlin
sentry {
  distribution {
    // Enable build distribution uploads
    enabled = providers.environmentVariable("GITHUB_ACTIONS").isPresent

    // Specify which build variants should include the auto-update SDK
    // These must be variants where the Sentry SDK is enabled (not in ignoredVariants)
    updateSdkVariants.set(setOf("nightly", "beta"))

    // Auth token (defaults to SENTRY_DISTRIBUTION_AUTH_TOKEN env var)
    authToken.set(System.getenv("SENTRY_DISTRIBUTION_AUTH_TOKEN"))
  }
}
```

This expects to find the environment variable `SENTRY_DISTRIBUTION_AUTH_TOKEN`, copy the token you generated in the preceding step to this variable in your CI environment.

### [Configuration Options](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#configuration-options)

| Option              | Description                                                              | Default                                  |
| ------------------- | ------------------------------------------------------------------------ | ---------------------------------------- |
| `enabled`           | Controls whether variants are uploaded for distribution                  | `false`                                  |
| `updateSdkVariants` | Set of Android build variants that should have the auto-update SDK added | `[]` (empty set)                         |
| `authToken`         | Integration token for build distribution operations                      | `SENTRY_DISTRIBUTION_AUTH_TOKEN` env var |
| `installGroups`     | Set of group names to tag builds with at upload time                     | `[]` (empty set)                         |

These options control different things and can be used independently:

* **`enabled`**: When `true`, all non-ignored variants are uploaded to Build Distribution. The `installGroups` are applied to all uploaded variants.
* **`updateSdkVariants`**: Only these variants get the auto-update SDK installed and the distribution properties (auth token, install groups) embedded in the app. Variants listed here must not be in `ignoredVariants`.
* **`installGroups`**: Applied at upload time to **all** uploaded variants (controlled by `enabled`), and embedded in the app for variants in `updateSdkVariants`.

This means you can upload all variants for distribution without the auto-update SDK, or add the auto-update SDK to specific variants without uploading others.

### [Auto-Installation](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#auto-installation)

When you add a variant to `updateSdkVariants`, the Sentry Gradle Plugin automatically:

1. Adds the `sentry-android-distribution` dependency to that variant
2. Embeds the distribution auth token and install groups in the app

No additional dependency declarations are needed.

## [Usage](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#usage)

### [Check for Updates](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#check-for-updates)

Once configured, you can check for updates in your application code. This is typically done at app startup or when the user navigates to a settings screen.

```kotlin
import io.sentry.Sentry
import io.sentry.UpdateStatus
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext

// Check for updates using coroutines
suspend fun checkForUpdate() {
    val status = withContext(Dispatchers.IO) {
        Sentry.distribution().checkForUpdateBlocking()
    }

    when (status) {
        is UpdateStatus.NewRelease -> {
            Sentry.distribution().downloadUpdate(status.info)
        }
        is UpdateStatus.UpToDate -> {
            // Current version is the latest
            Log.i("Sentry Distribution", "App is up to date")
        }
        is UpdateStatus.UpdateError -> {
            // An error occurred while checking for updates
            Log.i("Sentry Distribution", "Update check failed: ${status.message}")
        }
        is UpdateStatus.NoNetwork -> {
            // No network connection available
            Log.i("Sentry Distribution", "No network connection: ${status.message}")
        }
    }
}
```

## [Install Groups](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#install-groups)

Install groups let you control which build the Auto-Update SDK returns when checking for updates. The API always returns a single build — the latest (by semver version, then build number) whose install groups overlap with the filter. See the [Install Groups guide](https://docs.sentry.io/platforms/android/build-distribution/install-groups.md) for full details on how filtering works.

### [Gradle Configuration](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#gradle-configuration)

Add `installGroups` to the `distribution` block:

`build.gradle.kts`

```kotlin
sentry {
  distribution {
    enabled = true
    updateSdkVariants.set(setOf("nightly", "beta"))
    installGroups.set(setOf("alpha", "staging"))
  }
}
```

The Gradle plugin tags the uploaded build with these groups **and** embeds them in the app so the SDK sends them explicitly when checking for updates. This is the recommended approach — it ensures deterministic filtering regardless of how many builds share the same version number.

### [Programmatic Override](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#programmatic-override)

You can override the groups the SDK sends at runtime to filter by groups different from those included in the uploaded build:

```kotlin
SentryAndroid.init(context) { options ->
    options.distribution.installGroups = setOf("beta", "internal")
}
```

This overrides the groups used for filtering update checks. It does not change the groups the build was tagged with on Sentry.

## [Security Considerations](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#security-considerations)

* **Internal Use Only**: Never ship the auto-update SDK in production builds destined for public app stores
* **Token Security**: The distribution token is embedded in the app and can be extracted by reverse engineering. Use tokens with only the distribution read permission which is the minimum required permission for the auto-update SDK.

## [Best Practices](https://docs.sentry.io/platforms/android/build-distribution/auto-update.md#best-practices)

1. **Variant Separation**: Create dedicated build variants for internal distribution:

   ```groovy
   android {
       buildTypes {
           debug { /* ... */ }
           nightly { /* ... */ }
           beta { /* ... */ }
           release { /* ... */ }
       }
   }

   sentry {
       distribution {
           // Only enable for non-production variants
           updateSdkVariants = ["nightly", "beta"]
       }
   }
   ```

2. **Update Timing**: Check for updates at appropriate times:

   * On app launch automatically
   * In a settings/about screen (user-initiated)