Gradle Plugin
(5 minute setup time)
The Emerge Gradle Plugin allows you to upload Android builds (AABs or APKs), including any obfuscation mappings (R8, Proguard) to Emerge directly in your Gradle build step.
Setup
We'd recommend uploading release builds to Emerge as part of your CI build process, specifically on any event that should trigger a size analysis. Examples of these are:
- When pushing or merging to specific branches (main/release).
- On any PR to the main branch.
Add gradlePluginPortal to your plugin repositories
The Emerge Gradle Plugin lives in the Gradle plugin portal repository.
You'll need to add the repository information to your settings.gradle(.kts)
to properly pull the plugin.
pluginManagement {
repositories {
...
gradlePluginPortal()
}
}
pluginManagement {
repositories {
...
gradlePluginPortal()
}
}
Add the Emerge Gradle Plugin to your project
In your app's build.gradle(.kts)
file, add the Emerge plugin to your plugins block. Add an emerge
block as well where we'll configure the required parameters to upload your build.
A full example is shown below, the specific parameters are explained in the following section.
plugins {
...
id("com.emergetools.android") version "1.0.0"
}
...
emerge {
apiToken.set(System.getenv("EMERGE_API_TOKEN"))
vcsOptions {
sha.set("git sha")
baseSha.set("git base_sha")
prNumber.set("your_pr_number")
branchName.set("branch_name")
repoName.set("EmergeTools/repo_name")
}
// Optional
buildType.set("alpha|beta|prod") // defaults to "release" if not provided
}
plugins {
...
id 'com.emergetools.android"
}
...
emerge {
apiToken = System.getenv("EMERGE_API_TOKEN")
vcsOptions {
sha = 'git sha'
baseSha = 'git base_sha'
prNumber = 'your_pr_number'
branchName = 'branch_name'
repoName = 'EmergeTools/repo_name'
}
// Optional
buildType = 'alpha|beta|prod' // defaults to "release" if not provided
}
Create Emerge API token and use with plugin
First, create an Emerge API token. You can create one from your Emerge profile page.


Create an Emerge API key in your Emerge profile page
We'd recommend storing this API key in a secrets store, environment variable, or properties file (like gradle.properties
) that will be used at build time. We use an environment variable above as an example.
Set the apiToken
parameter in the emerge { }
plugin block to the resolved value from whatever secret storage means you use.
Configure options
A few extra arguments are required for PR diffs (comments, status checks) to work:
- In the
vcsParams
block:- sha: The SHA of the commit that your app was built from.
- baseSha: The SHA of the base commit your app was built from. For example, the last commit from
main
before you created the current branch. - branch: The name of your current git branch.
- repoName: Name of your GitHub repository. (should follow the pattern
Organization/repo_name
) - prNumber: Number of the pull request that triggered this build.
Optionally, include the following for additional information:
- buildType: A string indicating what type of build this is.
"release"
by default if not specified. For example, this could be something like"alpha"
,"beta"
or anything of your choosing depending on the type of build you're uploading.
These parameters work with the Emerge GitHub app to find the base build that was already uploaded and post the comment to your PR.
Usage
The Emerge Gradle Plugin generates a task to build an AAB or an APK for every variant of your application. These tasks are very similar to the default Android Gradle Plugin assemble{variant}
and bundle{variant}
tasks:
./gradlew assembleEmerge{variant}
or ./gradlew bundleEmerge{variant}
Any args passed after the command will be passed directly to the build task.
Common tasks
Upload a release AAB (recommended)
Run ./gradlew bundleEmergeRelease
.
Upload a release APK with obfuscation mappings
Run ./gradlew assembleEmergeRelease
.
Upload custom variants
Run ./gradlew bundleEmerge{variant}
, example: ./gradlew bundleEmergeAlpha
.
Manual uploads
We don't recommend performing manual uploads, as uploads are grouped by buildType
and can affect what builds are shown from your dashboard. Manual uploads without proper configurations could show inaccurate jumps/reductions in app size that isn't reflected from your true CI release builds.
If you do wish to perform manual uploads, any of the above tasks can be run locally. We'd recommend adjusting the local parameters for vcsOptions
and specifying a buildType
of "test"
or something different than your CI uploads.
Congrats on setting up the Emerge Gradle Plugin!
After uploading, Emerge will run analysis on the uploaded build. If you haven't, set up GitHub and/or status checks by following our GitHub docs.
For more details about the upload process and Emerge's supported artifact types, see
the Uploading Basics.
Updated about 1 month ago