Overview

Emerge integrates with your CI workflow to automatically measure the impact of changes and alert you to regressions. Setup our Fastlane plugin 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?

Emerge supports uploading archives and test builds for size analysis, but there are pros and cons of each. For reliable PR diffs, we recommend uploading each time a branch build is triggered from pushing a commit to a pull request and when pull requests are merged to master. The builds of master act as the base builds which PR builds are compared to.

📘

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 master. The base build and PR build need to use the same configuration (test or archive) to ensure proper diffing. With this setup every PR will have a location it branched from master 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.

🚧

dSYMS

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.

Examples

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 Buck or Bazel. This setup allows PR diffs to be extremely accurate because an archive build is compared.

Archive

Test

master branch

✅ Uploaded to Emerge with "release" build type and buildId

feature branch

✅ Uploaded to Emerge with baseBuildId corresponding to a build of the master branch

✅ Not used by Emerge

You can also batch builds of the master branch using a merge queue. Instead of each PR instantly merging to master 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 size teams that want to ensure no unexpected size changes make it to master. Accurate size measurements will be computed periodically on archives of the master branch.

Archive

Test

Hourly master builds
Often referred to as Alpha/Beta

✅ Uploaded to Emerge with "release" build type. Used to show app size over time on the dashboard

master branch

✅ Uploaded to Emerge with buildId

feature branch

✅ Uploaded to Emerge with baseBuildId corresponding to a build of the master branch


What’s Next