Build Distribution

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 (version 1.35.0 or higher) or Sentry CLI

Uploading With Fastlane

The Fastlane plugin can be used to upload XCArchive or IPA builds to Sentry. On GitHub Actions, Fastlane will automatically detect your build's metadata and include it in the upload. In other Continuous Integration (CI) environments, you may need to manually set metadata values.

1. Configure the Sentry Fastlane plugin (version 2.2.0):

   Ruby

   Copied

   bundle exec fastlane add_plugin fastlane-plugin-sentry
   

2. Set up SENTRY_AUTH_TOKEN in your environment (you can generate a token here)

3. In FastFile, add a call to sentry_upload_build after your build step.

   Uploading an XCArchive (preferred):

   When using build_ios_app, the XCArchive path is automatically detected from SharedValues::XCODEBUILD_ARCHIVE:

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
     build_ios_app(
       scheme: 'YourScheme',
       configuration: 'Release'
     )
     sentry_upload_build(
       org_slug: 'your-org',
       project_slug: 'your-project',
       build_configuration: 'Release'
     )
   end
   

   You can also explicitly specify the xcarchive_path:

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
     sentry_upload_build(
       org_slug: 'your-org',
       project_slug: 'your-project',
       xcarchive_path: 'path/to/YourApp.xcarchive',
       build_configuration: 'Release'
     )
   end
   

   Uploading an IPA:

   When using build_ios_app, the IPA path is automatically detected from SharedValues::IPA_OUTPUT_PATH.

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
     build_ios_app(
       scheme: 'YourScheme',
       configuration: 'Release'
     )
     sentry_upload_build(
       org_slug: 'your-org',
       project_slug: 'your-project',
       build_configuration: 'Release'
     )
   end
   

   To upload an IPA instead of the XCArchive, explicitly specify ipa_path:

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
     build_ios_app(
       scheme: 'YourScheme',
       configuration: 'Release'
     )
     sentry_upload_build(
       org_slug: 'your-org',
       project_slug: 'your-project',
       ipa_path: 'path/to/YourApp.ipa',
       build_configuration: 'Release'
     )
   end
   

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

   

The Fastlane plugin automatically detects the following build metadata. If needed, the metadata values can be overridden by passing parameters to sentry_upload_build:

sentry_upload_build(
  org_slug: 'your-org',
  project_slug: 'your-project',
  xcarchive_path: 'path/to/YourApp.xcarchive', # or ipa_path: 'path/to/YourApp.ipa'
  build_configuration: 'Release',
  # Optional metadata overrides:
  head_sha: 'abc123',
  base_sha: 'def456',
  vcs_provider: 'github',
  head_repo_name: 'organization/repository',
  base_repo_name: 'organization/repository',
  head_ref: 'feature-branch',
  base_ref: 'main',
  pr_number: '42'
)

See the Fastlane repo for more information.

Uploading with the Sentry CLI

1. Install the sentry-cli (version 3.3.0)

   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 XCArchive (preferred) or IPA

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

   Bash

   Copied

   sentry-cli build upload app.xcarchive \
     --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 build directly on your iOS device. For more information on installing enterprise apps, see Apple's documentation on installing custom apps.

Upload Metadata

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

* required field

Build Configuration

Features such as automatically comparing the head build against the base build will only compare builds of the same build configuration. This is important to consider when setting up Size Analysis in your CI. For example, Release and Debug builds can be drastically different depending on the compiler and linker settings used during the build process. Trying to compare the two would give unexpected results.