Integrating Into CI

Set up the integration in CI to receive automated size change notifications

The GitHub integration brings Size Analysis directly into your pull request workflow by adding status checks. This alerts developers to the size impact their code changes have on the app build, and can optionally block the pull request from being merged on large size increases.

Size Analysis works by comparing a head vs a base build, similar to how code review compares your new code to the baseline code.

  1. Install the Sentry Github App by following the installation instructions in the GitHub integration documentation.

    a. If you have previously installed the Sentry App, ensure you have accepted the latest permissions in order to receive Status Checks.

  2. Set up Size Analysis by following the guide for iOS or Android.

  3. Modify an existing workflow or create a new workflow to upload base builds from your main or default branch to Sentry:

sentry_size_analysis_main.yml
Copied
name: Sentry Size Analysis Upload

on:
  push:
    branches: [main]

jobs:
  build_and_upload:
    # Add your upload command here from the respective iOS or Android guide

Example workflows:

Confirm that builds uploaded from this workflow have the correct sha metadata value, as well as no base_sha being set.

  1. Modify an existing workflow or create a new workflow to upload head builds from your pull request branches:
sentry_size_analysis_pull_request.yml
Copied
name: Sentry Size Analysis Upload

on:
  pull_request:
    branches: [main]

jobs:
  build_and_upload:
    # Add your upload command here from the respective iOS or Android guide

Example workflows:

Confirm that builds uploaded from this workflow have the correct sha and base_sha metadata values.

For more options on controlling which builds get processed for Size Analysis, see Configuring Size Analysis Uploads.

  1. Confirm the status check appears

After configuring both workflows and sending the correct metadata, the status check should appear on every commit:

  1. View the detailed breakdown

Clicking on the "Details" button above should bring you to a more detailed breakdown of the changes.

By default, status checks appear as neutral and won't block pull requests. You can configure rules to automatically fail status checks when size thresholds are exceeded.

  1. Go to Settings > Projects, then select your project
  2. In the left sidebar, click on Mobile Builds
  3. Toggle Enable Status Checks if not already enabled
  4. Click Create Status Check Rule to create a new status check rule

Each rule consists of:

Metric: Choose what to measure

  • Install/Uncompressed Size - Total unpacked application size
  • Download Size - Compressed/downloadable application size

Measurement Type: How the threshold is applied

  • Absolute Size - Fail if current size exceeds threshold (e.g., max 50 MB)
  • Absolute Diff - Fail if size increases by more than threshold (e.g., max 5 MB increase)
  • Relative Diff - Fail if size increases by more than threshold percentage (e.g., max 10% increase)

Threshold: Numeric value for the limit

  • For Absolute and Absolute Diff: value in MB
  • For Relative Diff: percentage value

Filters (Optional): Apply rule only to specific builds

  • app_id - Target specific app ids (e.g., com.example.app)
  • git_head_ref - Target specific branches (e.g., main, release/*)
  • build_configuration_name - Target specific build types (e.g., Release)
  • platform_name - Target specific platforms (e.g., apple, android)

Here's an example configuration that prevents install size from increasing by more than 5 MB:

  • Metric: Install/Uncompressed Size
  • Measurement: Absolute Diff
  • Threshold: 5 MB
  • Filters: build_configuration_name is Release

When this rule triggers, the status check will fail on the pull request.

You can create multiple rules for different scenarios:

  • Enforce absolute maximum size limits
  • Prevent large incremental increases
  • Apply different thresholds to different platforms or configurations

Rules are evaluated independently. If any rule's threshold is exceeded, the status check fails.

  • If status checks are disabled, no checks will appear on pull requests
  • If status checks are enabled but no rules are configured, checks will post as neutral (won't block PRs) but will still show size change information
  • If rules are configured, checks will pass or fail based on whether thresholds are exceeded

Check that:

  • The Sentry GitHub App is installed and has access to your repository
  • You're correctly uploading builds for size analysis from all base branch builds
  • You're correctly uploading builds for size analysis from the PR branch.
  • Your builds that you want to compare have the same build configuration (for example, both are Release builds)
  • Your builds contain all the required metadata

The first time you set up Size Analysis, your main branch may not have any builds yet:

  1. Merge a PR or push to your main branch to trigger a build
  2. Future PRs will be able to compare against this base build

This could be due to a few things:

  1. The wrong base build is being selected. Check that the Git information in both head/base builds match what you expect for your pull request.
  2. The compiler optimized code in a different way. The analysis is being performed on the compiled output of the app, and sometimes the compiler can optimize code in slightly different ways depending on your code changes, for example with function outlining.
  3. The build environment is different between head/base builds. For iOS analyses, make sure the same version of Xcode is being used for both the builds.
Previous
Size Analysis
Next
Build Distribution
Was this helpful?
Help improve this content
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").