Emerge integrates with your CI workflow to automatically measure the impact of changes and alert you to regressions. Setup our Fastlane plugin or GitHub Action to upload builds and our GitHub App to receive automated pull request comments.

There are many ways to integrate Emerge depending on your CI setup. Here we've documented a few examples and best practices, but you can always get in touch at [email protected] to work out a specific solution for your company.

Which builds should I upload from CI?

On iOS, Emerge supports uploading archives or test builds for size analysis. On Android, Emerge supports any build variant (e.g. release, debug) of your choice, but there are pros and cons to each.

For reliable PR diffs, we recommend uploading a branch build after pushing a commit to a pull request and when pull requests are merged to your default branch, i.e. main or master. The builds of your default branch act as the base builds and are compared against PR builds.


Base builds

You'll need to provide a base build to generate a comparison, this is typically done by building after a PR has been merged to main. The base build and PR build need to use the same configuration (test or archive for iOS, build variant for Android) to ensure proper diffing. With this setup, every PR will have a location it branched from main to generate a comparison.


Test builds

Test builds are created by xcodebuild test when running unit tests in CI. These builds often use the Debug configuration and are built for the simulator architecture. Emerge supports these builds for size breakdowns and build diffs. The overall app size will be inaccurate because extra compiler optimizations are skipped and the binary generated for the simulator has a different format than device binaries. Comparisons will be accurate and allow you to find unexpected size increases, potential savings, and unused code.



Debugging information in symbol files are used by Emerge to accurately attribute app size. Our Fastlane plugin automatically finds these and uploads them as long as your build setting generates them. The Fastlane documentation includes more details on how to enable them for test builds.

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.


Debug build variant

Debug builds are created by building the debug build variant in Android Studio, or with the Gradle commands ./gradlew assembleDebug (for APKs) or ./gradlew bundleDebug (for app bundles).

In almost all cases, debug builds should not be used for any performance or app size benchmarking, including Emerge's analysis. By default, Proguard/R8 will not be enabled for debug builds and therefore won't perform significant code optimization that will both reduce app size and improve app performance. shrinkResources likely also won't be enabled for debug builds, leaving unused resources in your app.

Debug builds can still be uploaded and processed with Emerge nonetheless, and all diffing, insights and other functionality will be accurate.

Release or other build variants

Release builds are created by building the release build variant in Android Studio, or with the Gradle commands ./gradlew assembleRelease (for APKs) or ./gradlew bundleRelease (for app bundles). Other variants or flavors can be created in a similar manner depending on your app's specific build configuration.

We'd most recommend uploading a release variant of your app to be processed by Emerge, with Proguard/R8 enabled along with any other optimizations you ship to your end-users. By uploading the same build your end-users use, Emerge can generate the best analysis of exactly what your users will receive when using your app.

You can upload multiple different built variants as well, just specify the buildType parameter when uploading your AAB or APK.

Bundles vs APKs

You can upload either an APK or an AAB to Emerge. Emerge will not diff builds of different formats, so we recommend keeping your build artifacts consistent. For example, if you upload an AAB from your main branch, and upload an APK from a feature branch off the main branch, we cannot diff between an AAB and an APK.

We'd recommend uploading an AAB as it is now required for new apps as of August 2021). AABs allow Google Play to deliver your app to end-users containing only the resources, assets, code, and languages that their specific device needs, resulting in potentially large size savings. This splitting optimizes your app so users download only what their specific device needs. Read more about AABs in our docs.

Emerge's will analyze the outputted APKs Google Play would serve for your AAB on a Pixel 5 running Android 11.

If your team hasn't yet migrated to using AABs, we do accept Univeral APKs or your own split APKs. To include Proguard mappings, zip your APK(s) with the Proguard mappings at the top level of the zip with the APK(s), named proguard.txt, mapping.txt or proguard.pro.


Archive on feature branches

This is best for large organizations that ensure the release configuration of their app builds successfully with every change. It requires an efficient CI pipeline, often with some form of networking caching such as Gradle, Buck or Bazel. This setup allows PR diffs to be extremely accurate because an archive build is compared.

main branchβœ… Uploaded to Emerge with "release" buildType and buildId.
feature branchβœ… Uploaded to Emerge with baseSha corresponding to a build of the main branch.βœ… Not used by Emerge

You can also batch builds of the main branch using a merge queue. Instead of each PR instantly merging to main they are batched together with a standard cadence (ex: every hour). This reduces the load on CI machines.

Test on feature branches

Ideal for medium-sized teams that want to ensure no unexpected size changes make it to main. Accurate size measurements will be computed periodically on archives of the main branch.

Hourly main builds
Often referred to as Alpha/Beta
βœ… Uploaded to Emerge with "release" buildType. Used to show app size over time on the dashboard
main branchβœ… Uploaded to Emerge with buildId.
feature branchβœ… Uploaded to Emerge with baseSha corresponding to a build of the main branch.

What’s Next