Build Distribution
Distribute app builds to internal teams and beta testers.
This feature is available only if you're in the Early Adopter program. Features available to Early Adopters are still in-progress and may have bugs. We recognize the irony.
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.
Integrate Build Distribution into your CI pipeline to automatically distribute builds to your teams.
You can follow the platform guides to learn how to upload builds for distribution:
Below is the metadata included in your build, regardless of the platform.
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) to control update visibility between builds. Can be specified multiple times |
* required field
You can control which uploaded builds are processed for Build Distribution in Sentry Settings. Go to your project's Mobile Builds settings.
By default, Build Distribution processes all uploaded builds. You can configure filters to only distribute builds matching specific criteria, such as git_head_ref: main, build_configuration_name: Release, or app_id: com.example.app.
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.
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.
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.
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.
- Branch-based testing: Tag CI builds with the branch name so developers only receive updates from their own branch.
- Staged rollouts: Use groups like
"alpha","beta", and"internal"to control which teams receive which builds. - Team separation: Give each team its own install group so they only see builds relevant to them.
For platform-specific setup instructions, see:
Once builds are uploaded to Sentry, your team members and beta testers can download them through the Sentry web interface.
- Open the URL printed to the console after uploading the build
- Click the Install button on the right side of the page
- Either scan the QR code from a mobile device or click the Download button to download the build directly
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").