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 comparisons 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 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 your CI to upload the following builds:

1. All base builds. This serves as a reference point for comparisons from future head builds.
2. All head builds. Uploading head builds is most commonly done from CI that is run on each pull request.

📘

We recommend the Emerge Fastlane Plugin for iOS and the Emerge Gradle Plugin for Android for the simplest integration. Follow those guides for setup and return here in order to test the integration.

If you are not using Fastlane or Gradle, we offer the REST API or the Emerge CLI .

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.

🚧

### Unique apps per SHA

Emerge will compare uploads by SHA then appId (packageName on Android, bundleId on iOS) to ensure accuracy. It’s important to make sure there aren’t multiple uploads from the same commit SHA with the same appId, as this could result in inaccurate comparisons.

For example, if you upload a debug and release build on each commit, one should be com.company.app.debug and the other should be com.company.app. Otherwise, the release build could be compared against the debug build, resulting in incorrect comparisons.

If your build system does not have separate appIds, you can use the parameter appIdSuffix for iOS uploads (which is an option in the fastlane action) and applicationIdSuffix for Android apps.

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.

Special notes for cross-platform Monorepos

Monorepos, specifically those that contain both iOS and Android projects, introduce some complexity into CI uploads.

Emerge relies on a base build being present for size, performance, and snapshot checks. If you open a pull request with commit SHA bar against base commit SHA foo, we first need to find the Emerge build associated with commit foo. For a Monorepo setup, this can present a challenge if the base commit for the pull request did not trigger a build for the respective platform, e.g. an iOS pull request was branched from an Android commit.

To ensure every code change has a base to compare against, make sure to upload both iOS and Android builds as part of the main branch push. In a GitHub workflow, this looks like:

name: Emerge Android upload

on:
  push:
    branches: [ main ]
    # Notice we only specify a path for pull_request events, not pushes to main
  pull_request:
    branches: [ main ]
    paths: [android/**]

Doing so for your CI system will ensure that no matter the platform a pull request targets, there always will be both an iOS and Android base build present to compare against.