feat(preprod): Add build distribution docs (#15463)

chromy · runningcode · claude · web-flow · commit c6c0a8395236 · 2025-11-25T16:08:29.000+01:00
## DESCRIBE YOUR PR This adds docs for mobile Build Distribution which is going into EA. Build Distribution is very similar to Size Analysis so we mostly reused or shared the existing content. We'll add more Build Distribution specific content as they land going towards GA. Fixes EME-453 ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.):  - [ ] Other deadline: - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [x] Checked Vercel preview for correctness, including links - [x] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Nelson Osacky <nelson.osacky@sentry.io> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
diff --git a/docs/platforms/android/build-distribution/index.mdx b/docs/platforms/android/build-distribution/index.mdx
@@ -0,0 +1,43 @@
+---
+title: Build Distribution
+sidebar_title: Build Distribution
+sidebar_order: 5250
+description: Upload Android builds to Sentry for distribution to internal teams and beta testers.
+---
+
+<Include name="feature-available-for-user-group-early-adopter" />
+
+[Build Distribution](/product/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](#uploading-with-gradle) | [Sentry CLI](#uploading-with-the-sentry-cli)
+
+### Uploading With Gradle
+
+<Include name="build-distribution/upload-gradle" />
+
+### Uploading With the Sentry CLI
+
+<Include name="size-analysis/upload-cli-android" />
+
+## Downloading Builds
+
+<Include name="build-distribution/download" />
+
+<Include name="build-distribution/download-android" />
+
+## Upload Metadata
+
+<Include name="size-analysis/upload-metadata" />
+
+### Build Configuration
+
+<Include name="size-analysis/upload-metadata" />
+
+<PageGrid />
diff --git a/docs/platforms/apple/guides/ios/build-distribution/index.mdx b/docs/platforms/apple/guides/ios/build-distribution/index.mdx
@@ -0,0 +1,40 @@
+---
+title: Build Distribution
+sidebar_order: 5250
+description: Upload iOS builds to Sentry for distribution to internal teams and beta testers.
+---
+
+<Include name="feature-available-for-user-group-early-adopter" />
+
+[Build Distribution](/product/build-distribution) helps you securely distribute iOS builds to your internal teams and beta testers.
+Streamline your distribution workflow with automated uploads from CI.
+
+## Getting Started
+
+**Accepted Formats**: XCArchive
+
+**Upload Mechanisms**: [Fastlane Plugin](#uploading-with-fastlane) (version 1.35.0 or higher) _or_ [Sentry CLI](#uploading-with-the-sentry-cli)
+
+### Uploading With Fastlane
+
+<Include name="size-analysis/upload-fastlane" />
+
+### Uploading with the Sentry CLI
+
+<Include name="size-analysis/upload-cli-ios" />
+
+## Downloading Builds
+
+<Include name="build-distribution/download" />
+
+<Include name="build-distribution/download-ios" />
+
+## Upload Metadata
+
+<Include name="size-analysis/upload-metadata" />
+
+### Build Configuration
+
+<Include name="size-analysis/build-configuration-ios" />
+
+<PageGrid />
diff --git a/docs/platforms/dart/guides/flutter/build-distribution/index.mdx b/docs/platforms/dart/guides/flutter/build-distribution/index.mdx
@@ -0,0 +1,31 @@
+---
+title: Build Distribution
+sidebar_order: 5250
+description: Upload Flutter builds to Sentry for distribution to internal teams and beta testers.
+---
+
+<Include name="feature-available-for-user-group-early-adopter" />
+
+<Include name="build-distribution/intro" />
+
+## Getting Started - iOS
+
+<Include name="build-distribution/getting-started-ios" />
+
+## Getting Started - Android
+
+<Include name="build-distribution/getting-started-android" />
+
+## Downloading Builds
+
+<Include name="build-distribution/downloading-builds" />
+
+## Upload Metadata
+
+<Include name="size-analysis/upload-metadata" />
+
+### Build Configuration
+
+<Include name="size-analysis/build-configuration-general" />
+
+<PageGrid />
diff --git a/docs/platforms/react-native/build-distribution/index.mdx b/docs/platforms/react-native/build-distribution/index.mdx
@@ -0,0 +1,32 @@
+---
+title: Build Distribution
+sidebar_title: Build Distribution
+sidebar_order: 5250
+description: Upload React Native iOS and Android builds to Sentry for distribution to internal teams and beta testers.
+---
+
+<Include name="feature-available-for-user-group-early-adopter" />
+
+<Include name="build-distribution/intro" />
+
+## Getting Started - iOS
+
+<Include name="build-distribution/getting-started-ios" />
+
+## Getting Started - Android
+
+<Include name="build-distribution/getting-started-android" />
+
+## Downloading Builds
+
+<Include name="build-distribution/downloading-builds" />
+
+## Upload Metadata
+
+<Include name="size-analysis/upload-metadata" />
+
+### Build Configuration
+
+<Include name="size-analysis/build-configuration-general" />
+
+<PageGrid />
diff --git a/docs/product/build-distribution/index.mdx b/docs/product/build-distribution/index.mdx
@@ -0,0 +1,32 @@
+---
+title: Build Distribution
+sidebar_order: 137
+description: Distribute app builds to internal teams and beta testers.
+---
+
+<Include name="feature-available-for-user-group-early-adopter" />
+
+Build Distribution enables you to securely distribute app builds to your internal teams and beta testers. Upload builds from CI to streamline your distribution workflow, manage access control, and track installation analytics.
+
+### CI Integration
+
+Integrate Build Distribution into your CI pipeline to automatically distribute builds to your teams.
+
+## Upload Guides
+
+You can follow the platform guides to learn how to upload builds for distribution:
+
+- [iOS](/platforms/apple/guides/ios/build-distribution/)
+- [Android](/platforms/android/build-distribution/)
+
+### Upload Metadata
+
+Below is the metadata included in your build, regardless of the platform.
+
+<Include name="size-analysis/upload-metadata" />
+
+## Downloading Builds
+
+<Include name="build-distribution/download" />
+
+<PageGrid />
diff --git a/includes/build-distribution/download-android.mdx b/includes/build-distribution/download-android.mdx
@@ -0,0 +1,6 @@
+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).
diff --git a/includes/build-distribution/download-ios.mdx b/includes/build-distribution/download-ios.mdx
@@ -0,0 +1 @@
+After downloading, you can install the build directly on your iOS device. For more information on installing enterprise apps, see [Apple's documentation on installing custom apps](https://support.apple.com/en-us/118254).
diff --git a/includes/build-distribution/download.mdx b/includes/build-distribution/download.mdx
@@ -0,0 +1,10 @@
+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
+
+![Install link highlighted =400x](./images/install-link.png)
+
+3. Either scan the QR code from a mobile device or click the **Download** button to download the build directly
+
+![Install modal with QR code =400x](./images/install-qr.png)
diff --git a/includes/build-distribution/downloading-builds.mdx b/includes/build-distribution/downloading-builds.mdx
@@ -0,0 +1,9 @@
+<Include name="build-distribution/download" />
+
+### iOS
+
+<Include name="build-distribution/download-ios" />
+
+### Android
+
+<Include name="build-distribution/download-android" />
diff --git a/includes/build-distribution/getting-started-android.mdx b/includes/build-distribution/getting-started-android.mdx
@@ -0,0 +1,14 @@
+**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](#uploading-android-builds-with-gradle) | [Sentry CLI](#uploading-android-builds-with-the-sentry-cli)
+
+### Uploading Android Builds With Gradle
+
+<Include name="build-distribution/upload-gradle" />
+
+### Uploading Android Builds With the Sentry CLI
+
+<Include name="size-analysis/upload-cli-android" />
diff --git a/includes/build-distribution/getting-started-ios.mdx b/includes/build-distribution/getting-started-ios.mdx
@@ -0,0 +1,7 @@
+**Accepted Formats**: XCArchive
+
+**Upload Mechanism**: [Sentry CLI](#uploading-ios-builds-with-the-sentry-cli)
+
+### Uploading iOS Builds With the Sentry CLI
+
+<Include name="size-analysis/upload-cli-ios" />
diff --git a/includes/build-distribution/images/install-link.png b/includes/build-distribution/images/install-link.png
diff --git a/includes/build-distribution/images/install-qr.png b/includes/build-distribution/images/install-qr.png
diff --git a/includes/build-distribution/intro.mdx b/includes/build-distribution/intro.mdx
@@ -0,0 +1,2 @@
+[Build Distribution](/product/build-distribution) helps you securely distribute iOS and Android builds to your internal teams and beta testers.
+Streamline your distribution workflow with automated uploads from CI.
diff --git a/includes/build-distribution/upload-gradle.mdx b/includes/build-distribution/upload-gradle.mdx
@@ -0,0 +1 @@
+<GradleUploadInstructions feature="distribution" />
diff --git a/includes/size-analysis/upload-gradle.mdx b/includes/size-analysis/upload-gradle.mdx
@@ -1,100 +1 @@
-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](/platforms/android/configuration/gradle/) with at least version `6.0.0-beta.2`
-
-2. Set the auth token as an environment variable to be used when running your release build.
-
-   <OrgAuthTokenNote />
-
-   ```bash
-   export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
-   ```
-
-3. Enable uploading for size analysis for CI builds.
-
-   ```kotlin {filename:build.gradle.kts}
-   sentry {
-     sizeAnalysis {
-       enabled = providers.environmentVariable("GITHUB_ACTIONS").isPresent
-     }
-   }
-   ```
-
-   ```groovy {filename:build.gradle}
-   sentry {
-     sizeAnalysis {
-       enabled = providers.environmentVariable("GITHUB_ACTIONS").present
-     }
-   }
-   ```
-
-4. Invoke the following Gradle tasks to build your app and trigger the upload.
-
-   ```aab {filename:aab}
-   ./gradlew bundleRelease
-   ```
-
-   ```apk {filename:apk}
-   ./gradlew assembleRelease
-   ```
-
-5. After an upload has successfully processed, confirm the metadata is correct in the Sentry UI
-
-   ![Upload metadata =400x](./images/android-metadata.png)
-
-### 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:
-
-```kotlin {filename:build.gradle.kts}
-sentry {
-  sizeAnalysis {
-    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)
-  }
-}
-```
-
-```groovy {filename:build.gradle}
-sentry {
-  sizeAnalysis {
-    enabled = providers.environmentVariable("GITHUB_ACTIONS").present
-  }
-
-  vcsInfo {
-    headSha = 'abc123'
-    baseSha = 'def456'
-    vcsProvider = 'github'
-    headRepoName = 'organization/repository'
-    baseRepoName = 'organization/repository'
-    headRef = 'feature-branch'
-    baseRef = 'main'
-    prNumber = 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               |
+<GradleUploadInstructions feature="sizeAnalysis" />
diff --git a/public/platforms/android/build-distribution/images/android-metadata.png b/public/platforms/android/build-distribution/images/android-metadata.png
diff --git a/src/components/gradleFeatureConfig.tsx b/src/components/gradleFeatureConfig.tsx
@@ -0,0 +1,39 @@
+import {CodeBlock} from './codeBlock';
+import {CodeTabs} from './codeTabs';
+import {codeToJsx} from './highlightCode';
+
+type Props = {
+  feature: string;
+};
+
+export function GradleFeatureConfig({feature}: Props) {
+  return (
+    <CodeTabs>
+      <CodeBlock language="kotlin" filename="build.gradle.kts">
+        <pre>
+          {codeToJsx(
+            `sentry {
+  ${feature} {
+    enabled = providers.environmentVariable("GITHUB_ACTIONS").isPresent
+  }
+}`,
+            'kotlin'
+          )}
+        </pre>
+      </CodeBlock>
+
+      <CodeBlock language="groovy" filename="build.gradle">
+        <pre>
+          {codeToJsx(
+            `sentry {
+  ${feature} {
+    enabled = providers.environmentVariable("GITHUB_ACTIONS").present
+  }
+}`,
+            'groovy'
+          )}
+        </pre>
+      </CodeBlock>
+    </CodeTabs>
+  );
+}
diff --git a/src/components/gradleUploadInstructions.tsx b/src/components/gradleUploadInstructions.tsx
diff --git a/src/components/highlightCode.tsx b/src/components/highlightCode.tsx
diff --git a/src/mdxComponents.ts b/src/mdxComponents.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+After downloading, you can install the build directly on your iOS device. For more information on installing enterprise apps, see [Apple's documentation on installing custom apps](https://support.apple.com/en-us/118254).`