docs(build-distribution): Document install groups for auto-update SDK

docs/platforms/android/build-distribution/auto-update.mdx

@@ -70,20 +70,22 @@ This expects to find the environment variable `SENTRY_DISTRIBUTION_AUTH_TOKEN`,
 | `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) |
 
-<Alert level="info">
+These options control different things and can be used independently:
 
-The `updateSdkVariants` configuration controls which variants get the auto-update SDK installed. The `enabled` option controls whether all builds are uploaded. You can have builds uploaded without the auto-update SDK, or vice versa.
-The enabled option when set to true will upload all variants that are not ignored via the Sentry `ignoreVariants`, `ignoredBuildTypes`, or `ignoredFlavors` options.
+- **`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`.
 
-</Alert>
+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
 
 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 securely in the app
+2. Embeds the distribution auth token and install groups in the app
 
 No additional dependency declarations are needed.
 
@@ -125,6 +127,38 @@ suspend fun checkForUpdate() {
 }
 ```
 
+## 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](/platforms/android/build-distribution/install-groups/) for full details on how filtering works.
+
+### Gradle Configuration
+
+Add `installGroups` to the `distribution` block:
+
+```kotlin {filename:build.gradle.kts}
+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
+
+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
 
 - **Internal Use Only**: Never ship the auto-update SDK in production builds destined for public app stores

docs/platforms/android/build-distribution/install-groups.mdx

@@ -58,3 +58,31 @@ sentry_upload_build(
   install_groups: ['alpha', 'staging']
 )
 ```
+
+## How Install Groups Work With the Auto-Update SDK
+
+When the Auto-Update SDK checks for updates, the API returns the single latest build (highest semver version, with build number as tiebreaker) whose install groups overlap with the filter:
+
+- If the SDK **provides groups explicitly**, the API uses those to filter.
+- If the SDK **doesn't provide groups**, the API falls back to looking up the uploaded build by `buildVersion` and `buildNumber` and using that build's install groups. If multiple builds share the same version and build number, the API picks the most recently uploaded one, which may lead to unexpected results.
+
+We recommend configuring the SDK to send install groups explicitly to ensure deterministic filtering.
+
+### Gradle Plugin
+
+The Gradle plugin's `installGroups` config handles this automatically:
+
+1. **Upload**: Passes `--install-group` flags to sentry-cli so the build is tagged on Sentry.
+2. **Embed**: Writes the groups to `sentry-distribution.properties` inside the APK (as `io.sentry.distribution.install-groups-override`). The [Auto-Update SDK](/platforms/android/build-distribution/auto-update/) reads this value at runtime and sends the groups explicitly as query parameters.
+
+### Programmatic Override
+
+If you need the SDK to filter by different groups than what the build was uploaded with (for example, based on a feature flag or user setting), you can override them via `SentryOptions`:
+
+```kotlin
+SentryAndroid.init(context) { options ->
+    options.distribution.installGroups = setOf("beta", "internal")
+}
+```
+
+This overrides the groups the SDK sends when checking for updates. It does not change the groups the build was tagged with on Sentry.

docs/platforms/apple/guides/ios/build-distribution/auto-update.mdx

@@ -75,6 +75,14 @@ struct MyView: View {
 }
 ```
 
+## 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. Tag your builds with install groups at upload time using sentry-cli or the Fastlane plugin, and the API automatically filters update checks — a device running a build uploaded with `["beta"]` will only see updates from other `["beta"]` builds.
+
+Unlike Android, iOS builds are identified by the UUID of the app binary. However, UUID matching is not guaranteed to identify the exact build you uploaded — the UUID only changes when the main binary changes, so uploads that differ only in other files (such as images) won't be differentiated. For deterministic filtering, configure the SDK to [provide install groups explicitly](/platforms/apple/guides/ios/build-distribution/install-groups/#sdk-configuration).
+
+See the [Install Groups guide](/platforms/apple/guides/ios/build-distribution/install-groups/) for upload instructions and full details on how filtering works.
+
 ## Security Considerations
 
 - **Internal Use Only**: Never ship the auto-update SDK in production builds destined for public app stores

docs/platforms/apple/guides/ios/build-distribution/install-groups.mdx

@@ -36,3 +36,12 @@ sentry_upload_build(
   install_groups: ['alpha', 'staging']
 )
 ```
+
+## How Install Groups Work With the Auto-Update SDK
+
+When the [Auto-Update SDK](/platforms/apple/guides/ios/build-distribution/auto-update/) checks for updates, the API returns the single latest build (highest semver version, with build number as tiebreaker) whose install groups overlap with the filter:
+
+- If the SDK **provides groups explicitly**, the API uses those to filter.
+- If the SDK **doesn't provide groups**, the API looks up the uploaded build using the UUID of the app binary and uses that build's upload groups for filtering.
+
+UUID matching is not guaranteed to identify the build you uploaded. The UUID is only unique to an app's main binary, so an upload that only changes other files such as images won't be differentiated.

docs/product/build-distribution/index.mdx

@@ -37,15 +37,25 @@ By default, Build Distribution processes all uploaded builds. You can configure
 
 ## Install Groups
 
-Install groups let you tag builds with one or more group names to control update visibility. When a device checks for updates, you can provide a list of install groups — only builds that share at least one install group with this list will be returned as available updates.
+Install groups let you tag builds with one or more group names to control update visibility. When the Auto-Update SDK checks for updates, the API returns the single latest build (by semver version, then build number) that shares at least one install group with the request.
 
 This is useful when you have multiple distribution channels (for example, separate branches, teams, or rollout stages) and want to prevent builds from one channel from being offered as updates to another.
 
 ### How It Works
 
-When you upload a build, you can assign one or more install groups to it. If the Auto-Update SDK is provided install groups, it only returns builds that have overlapping groups.
+Install groups are configured in two places, which can be set independently:
 
-Matching requires two builds to have a non-empty intersection of their install groups. For example, a build tagged `["alpha", "staging"]` will see updates from a build tagged `["alpha", "beta"]` because both share `alpha`.
+1. **At upload time**: Tag each build with one or more group names (for example, `"alpha"`, `"staging"`).
+2. **At runtime (optional)**: The Auto-Update SDK can explicitly send install groups when checking for updates to override the default filtering.
+
+When the SDK checks for updates, the API returns the single latest build (highest semver version, with build number as tiebreaker) whose install groups overlap with the filter. Install groups for the filter are determined as follows:
+
+- If the SDK **provides groups explicitly**, the API uses those.
+- If the SDK **doesn't provide groups**, the API looks up the uploaded build matching the device's current version and uses that build's upload groups. On iOS, the lookup uses the UUID of the app binary. The UUID only changes when the main binary changes, so uploads that differ only in other files (such as images) won't be differentiated. On Android, it uses `buildVersion` and `buildNumber` — if multiple builds share the same values, the API picks the most recently uploaded one, which may lead to unexpected results.
+
+We recommend configuring the SDK to send install groups explicitly rather than relying on API-side inheritance. On Android, the [Gradle plugin](/platforms/android/build-distribution/install-groups/#gradle-plugin) `installGroups` config handles this automatically — it tags the upload **and** embeds the groups in the app so the SDK sends them with every update check.
+
+Matching uses OR logic: a build matches if it shares **at least one** group with the filter. For example, filtering with `["alpha", "staging"]` will match a build tagged `["alpha", "beta"]` because both share `alpha`. Builds with no install groups will not match any filtered request.
 
 ### Use Cases