Uploading Basics
Emerge receives builds created by your CI pipeline, along with additional metadata about where the build was generated. There are two kinds of uploads that are required: base builds and branch builds.
Upload from CI
Configuring automatic uploads from CI requires 2 steps, commonly done in two separate pull requests:
- A first PR to configure uploading a base build (usually the default branch, e.g.
main
ormaster
). This will upload a base build upon merging this first PR, which future pull requests will use as the base to create a diff from! - A second PR to configure uploading branch builds. Uploading branch builds is most commonly done from CI that is run on each pull request. This will create a diff against builds uploaded from your base branch, which we set up in step 1.
Base Builds
These are builds of your base branch, which will usually be the default branch, e.g. main
or master
. For the integration to work, a build needs to be built from every commit pushed to the base branch. These fields are supported:
Field | Required? |
---|---|
filename | Yes |
branch | Yes (should always be the name of your base branch) |
sha | Yes |
repoName | Yes |
buildType | No (defaults to release if not provided) |
Branch Builds
These are builds originating from an open pull request. Once base builds are being sent to Emerge, you can add branch build uploads to get your first PR breakdown. These fields are supported:
Field | Required? |
---|---|
filename | Yes |
branch | Yes |
sha | Yes |
baseSha | Yes |
repoName | Yes |
prNumber | Yes |
buildType | No (defaults to release if not provided) |
Base SHA
A base SHA must be included with branch builds, this ensures the correct build is used when generating your comparison.
Build Type
buildType
is an optional parameter that defaults to release
if not provided when uploading.
The buildType
is used to separate different types of uploads that might not be intended to be grouped together. Specifying a buildType
allows for viewing the dashboard pertaining to just builds matching the selected buildType
.

The dashboard dropdown allows you to show size trends for a specific buildType
.
As an example, let's say you want to track size changes for a specific APK you ship for x86 device architectures, then another APK that is the default release
build type. You would upload two builds to Emerge, one with the buildType
set to the name of that type, say x86
, and the other build you don't specify buildType
. This would result in a single Emerge dashboard with a dropdown for release
and x86
buildType
s, allowing you to see size trends only for each respective type.
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.
The sha
field should be the commit SHA that your upload was built from. Essentially, it 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 point in your git tree that your branch was created from. In essence, the baseSha
allows Emerge to identify all the changes on a branch. The baseSha
should remain the same for all builds on a branch, at least until the branch is rebased.
Both the sha
and baseSha
values should correspond to what your Version Control System uses. Providing a shortened value will result in errors, preventing Emerge from interacting with your VCS.
Supported Artifacts
Emerge supports the following artifacts uploaded for size analysis.
Name | Extension | Platform |
---|---|---|
Zipped XCArchive | .zip (zipped .xcarchive ) | iOS |
Zipped XCFramework | .zip (zipped .xcframework ) | iOS |
Android App bundle | .aab | Android |
APK | .apk | Android |
Zipped APK(s) with proguard mappings | .zip (zipped .apks (s) with a proguard.txt , mapping.txt proguard.pro , or proguard.map mapping file included).Note: We require one APK (the primary APK if uploading multiple APKs) to be named base.apk . | Android |
Zipped AAB with optional test APK | .zip (zipped .aab with an optional .apk test APK leveraging Emerge's test SDK) | Android |
Note: fastlane will zip artifacts by default if uploading through the Emerge fastlane plugin.
Dexguard support
Emerge supports deobfuscating builds obfuscated with Dexguard. Depending on your Dexguard configuration, you might need to provide different mapping files with your Emerge upload. Contact your Emerge team representative for more details specific to your configuration.
Updated 3 months ago