Integrating Into CI

Uploading from CI

With Emerge's CI integration, you can configure automated comparisons (PR Comments / Status Checks) to show in your VCS, making it easy for everyone in your organization to be aware of your performance metrics.

For CI builds to work, we require additional metadata to be included with the upload that describes where the build was generated. Following a standard Git Flow setup, this would typically be:

• Base build: a build from the main or master branch
• Head build: a build from a development branch, like a Pull Request

We recommend configuring this in two steps:

1. Create a PR to configure uploading a base build. Once this PR is merged, it will upload a base build which future pull requests can use as a base.
2. Create a second PR to configure uploading head builds. Uploading head builds is most commonly done from CI that is run on each pull request.

📘

The Emerge Fastlane Plugin (iOS) and Emerge Gradle Plugin (Android) make it easy to integrate Emerge into your CI pipeline. If your team doesn't use Fastlane or Gradle, you also have the option to use our REST API directly.

Metadata fields

The following metadata fields need to be included with your uploads in CI:

Build type

buildType is an optional parameter that defaults to release if not provided when uploading. We recommend changing this value for head builds (eg using pull_request) so that feature builds don't get mixed in with your release builds for tracking purposes.

You can set this value to anything you'd like. For example, you might want to track sizes per device architecture using x86_64 and arm64 build types.

SHA and base SHA

The sha and baseSha parameters are used to provide Emerge information about the position of your build within your version control system structure. Both values should be sent using the SHA's long form. If you send a shortened SHA value this may result in errors.

The sha field should be the commit SHA that your upload was built from. This represents the HEAD position for the build, whether the build is on main or a branch.

The baseSha field is used specifically for branch builds. This field represents the point in your git tree that your branch was created from, allowing Emerge to identify all the changes on a branch. The baseSha should remain the same for all builds on a branch, unless the branch is rebased.

Which builds should be uploaded?

For reliable PR diffs, we recommend uploading a branch build after pushing to a PR and when PRs are merged back to your default branch, i.e. main or master. Builds from your default branch act as base builds for comparison against branch builds.

It's also important to only compare builds generated from the same (or very similar) build configuration. For example, comparing a debug build against a release build will show unexpected results.

iOS

Test builds

Test builds for running unit tests in CI are created by the xcodebuild test command and generally use the Debug configuration and target the simulator architecture.

Emerge supports processing these builds with the caveat that the app size and performance may be inaccurate for what your user will see due to skipped compiler optimizations and the target architecture format. Comparisons will still be accurate and allow you to find unexpected size increases, potential savings, and unused code.

Archive builds

Archive builds are created by xcodebuild archive and are the most accurate representations of app size. These can be used to track size over time or generate PR diffs.

If your app supports iOS 10 or earlier you'll be building multiple architectures when submitting to the App Store. To save time when building for Emerge you can optionally disable the 32-bit architecture since only one CPU slice is needed to measure app size.

Android

Debug builds

Debug builds are created by using debug Gradle build variants.

Emerge supports processing these builds with the caveat that the app size and performance may be inaccurate for what your user will see. For example, Proguard/R8 code optimizations are disabled by default for debug builds. It's also likely that the shrinkResources Gradle configuration is disabled. Comparisons will still be accurate and allow you to find unexpected size increases, potential savings, and unused code.

Release builds

Release builds are created by using release Gradle build variants.

We recommend uploading release builds with Proguard/R8 optimizations enabled, as well as shrinkResources turned on.

AAB vs APK

Emerge supports both .aab and .apk formats, however, diffs must be between builds of the same format.

We recommend uploading AAB builds as they are now required for new apps (as of August 2021). For AAB builds, Emerge will analyze the outputted APKs Google Play would serve for your AAB on a Pixel 5 running Android 11.