Gradle Plugin

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.

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.