Size Analysis

Size Analysis helps monitor your mobile app's size in pre-production to prevent unexpected size increases (regressions) from reaching users. Aside from being courteous to your users, a smaller app size helps boost installation and retention rates, especially for customers with limited storage or slower connections.

Getting Started - iOS

Accepted Upload Formats: XCArchive (preferred) | IPA

Upload Mechanisms: Fastlane Plugin or Sentry CLI

Uploading iOS Builds 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 iOS Builds 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

   

Getting Started - Android

Accepted Upload Formats: AAB (preferred) | APK

Upload Mechanisms: Sentry CLI | Gradle

Uploading Android builds 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 AAB (preferred) or APK

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

   Bash

   Copied

   sentry-cli build upload app.aab \
     --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

   

Uploading Android Builds With Gradle

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 with at least version 6.1.0

2. Set the auth token as an environment variable to be used when running your release build.

   Copied

   export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___

3. Enable uploading for size analysis for CI builds.

   KotlinGroovy

   build.gradle.kts

   Copied

   sentry {
     sizeAnalysis {
       enabled = providers.environmentVariable("GITHUB_ACTIONS").isPresent
     }
   }

4. Invoke the following Gradle tasks to build your app and trigger the upload.

   Aab

   aab

   Copied

   ./gradlew bundleRelease

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

   

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:

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)
  }
}

Available vcsInfo properties:

Uploading Android Builds With Fastlane

The Fastlane plugin can be used to upload AAB or APK 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 AAB (preferred):

   When using the gradle action with bundle task, the AAB path is automatically detected from SharedValues::GRADLE_AAB_OUTPUT_PATH.

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
     gradle(
       task: 'bundle',
       build_type: 'Release'
     )
     sentry_upload_build(
       org_slug: 'your-org',
       project_slug: 'your-project',
       build_configuration: 'Release'
     )
   end
   

   You can also explicitly specify aab_path:

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
     gradle(
       task: 'bundle',
       build_type: 'Release'
     )
     sentry_upload_build(
       org_slug: 'your-org',
       project_slug: 'your-project',
       aab_path: 'app/build/outputs/bundle/release/app-release.aab',
       build_configuration: 'Release'
     )
   end
   

   Uploading an APK:

   When using the gradle action with assemble task, the APK path is automatically detected from SharedValues::GRADLE_APK_OUTPUT_PATH.

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
    gradle(
      task: 'assemble',
      build_type: 'Release'
    )
    sentry_upload_build(
      org_slug: 'your-org',
      project_slug: 'your-project',
      build_configuration: 'Release'
    )
   end
   

   You can also explicitly specify apk_path:

   Ruby

   Fastfile

   Copied

   lane :upload_to_sentry do
     gradle(
       task: 'assemble',
       build_type: 'Release'
     )
     sentry_upload_build(
       org_slug: 'your-org',
       project_slug: 'your-project',
       apk_path: 'app/build/outputs/apk/release/app-release.apk',
       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',
  aab_path: 'path/to/app.aab', # or apk_path: 'path/to/app.apk'
  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.

Upload Metadata

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

* required field

Build Configuration

Build configuration metadata keeps comparisons scoped to like-for-like builds. The Android Gradle plugin sends the build variant (for example, freeDebug or paidRelease). On iOS, set this to your Xcode build configuration, such as Debug, Staging, or Release.