--- updatedAt: 2025-07-09T16:43:05.000Z agentTools: projectIndex: https://docs.emergetools.com/llms.txt --- # Gradle Plugin (Android) The Emerge Gradle plugin is the recommended way to integrate with Emerge on Android. Its main features are: * Uploading builds to Emerge for size analysis, snapshot testing, reaper & performance analysis. * Automatically run snapshot tests for all Compose Previews * Integrate Reaper, Emerge's dead code detection SDK, with your app * Debug & run performance and snapshot tests locally # Quick setup (\~10 minutes) ### Apply the Emerge Gradle plugin to your application module In your application module's `build.gradle(.kts)`: ```kotlin build.gradle.kts (app) plugins { id("com.emergetools.android") version "" } ``` Latest Emerge Gradle plugin version: [![Gradle Plugin Portal Version](https://img.shields.io/gradle-plugin-portal/v/com.emergetools.android)](https://plugins.gradle.org/plugin/com.emergetools.android) ### Obtain an API key Follow our guide on [obtaining an API key](https://docs.emergetools.com/docs/uploading-basics#obtain-an-api-key). We recommend storing this token in a secrets store, an environment variable, or a Gradle property file. The example in this guide uses the `EMERGE_API_TOKEN` environment variable, which the Emerge plugin will pick up and set as the default value for `apiToken`. ### Run a preflight check Let's check that everything's setup properly by running one of Emerge's preflight tasks for size analysis, snapshots or Reaper. Run `./gradlew ::tasks` to see all available tasks. For demo purposes, we'll run a size analysis preflight task: `./gradlew ::emergeSizeAnalysisPreflightRelease` Which will give detailed output about the Emerge integration: ```shell shell › ./gradlew :app:emergeSizeAnalysisPreflightRelease > Task :app:emergeSizeAnalysisPreflightRelease ╔════════════════════════════════════════════════════╗ ║ Size analysis preflight check was successful (2/2) ║ ╠════════════════════════════════════════════════════╝ ╠═ ✅ Emerge API token set ╚═ ✅ Size analysis enabled ╔═════════════════════════════════════╗ ║ VCS Info check was successful (4/4) ║ ╠═════════════════════════════════════╝ ╠═ ✅ SHA: 123456789.. ╠═ ✅ Base SHA: 987654321.. ╠═ ✅ Branch name: main ╚═ ✅ PR number: 123 Size analysis preflight was successful! Upload & run size analysis on Emerge with ./gradlew :app:emergeUploadReleaseAab ``` If there are any issues or warnings, the preflight tasks should help you identify and address them before uploading to Emerge. Let the Emerge team know if you have any unexpected issues. > 👍 All done! > > You're ready to start using the Emerge Gradle plugin. Read on for some commonly used tasks. # Tasks Emerge offers numerous tasks to help facilitate common use cases. We recommend running these in CI to get the full functionality Emerge offers. ## Size | Task | Description | | -------------------------------------- | ----------------------------------------------------------------------------------------------- | | `emergeSizeAnalysisPreflight{Variant}` | Run a preflight check to validate if size analysis is properly set up for the specific variant. | | `emergeUpload{Variant}Apk` | Upload an APK matching the specified variant to Emerge for size analysis. | | `emergeUpload{Variant}Aab` | Upload an AAB matching the specified variant to Emerge for size analysis. | ## Snapshots | Task | Description | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `emergeSnapshotsPreflight{Variant}` | Run a preflight check to validate if snapshots are properly set up for the specific variant. | | `emergeUploadSnapshotBundle{Variant}` | Builds & uploads target & test APKs for the specified variant. Snapshots will be generated & saved in Emerge's cloud snapshot offering. | | `emergeLocalSnapshots{Variant}` | Run snapshot tests locally. | *Note: The local snapshots task relies on ADB to run. Ensure a device or emulator is\ connected/running and `ANDROID_HOME` set to the location of the Android SDK is on your `PATH`.* ## Reaper | Task | Description | | -------------------------------- | ---------------------------------------------------------------------------------------- | | `emergeReaperPreflight{Variant}` | Run a preflight check to validate if reaper is properly set up for the specific variant. | Reaper hooks into the default AGP `bundle{Variant}` task to upload the app to Emerge. Reaper requires the release app to be uploaded so Emerge can determine all classes present within the app to associate with reports. For full reaper details, see [Reaper Android](https://docs.emergetools.com/docs/reaper-setup-android). ## Performance | Task | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `emergeGeneratePerformanceProject` | Create a pre-configured Emerge performance module. Only available if `perfProjectPath` value is set and doesn't yet exist . | | `emergeUpload{Variant}PerfBundle` | Upload an AAB matching the specified variant to Emerge packaged with the `perfProjectPath`'s test APK. | | `emergeLocal{Variant}Test` | Run performance tests from `perfProjectPath` locally for debugging & testing. | *Note: If wanting to run size & custom performance tests for an upload, you can just use the `emergeUpload{variant}PerfBundle` task. We'll automatically run size analysis for the release build as well :smile:* # Configuration The Emerge Gradle plugin is designed to be configured in the application-level build.gradle(.kts) file of your project. The plugin automatically fetch an API token set as the `EMERGE_API_TOKEN` environment variable. If you wish to use a different variable or add custom logic, see the full configuration below. ## Full configuration ```kotlin build.gradle.kts (app) // app-module build.gradle.kts plugins { id("com.emergetools.android") } emerge { // If not explicitly set, Emerge uses the EMERGE_API_TOKEN env variable apiToken.set(System.getenv("EMERGE_API_TOKEN")) // Defaults to true, if true, dependency info (module & third party) is included in upload to Emerge includeDependencyInformation.set(true) // Optional, defaults to false, use to execute tasks without uploading to Emerge dryRun.set(false) verbose.set(false) vcs { // Optional, will attempt to set automatically using Git information. sha.set("..") // Optional, will attempt to set automatically using Git information. baseSha.set("..") // Optional, will attempt to set automatically using Git information. previousSha.set(".." // Optional, will attempt to set automatically using Git information. branchName.set("my-feature") prNumber.set("123") gitHub { // Required for CI status checks (only if using GitHub) - Emerge will attempt to set with GitHub event info repoOwner.set("..") // Required for CI status checks (only if using GitHub) - Emerge will attempt to set with GitHub event info repoName.set("..") // Optional, defaults to true, include GitHub event data in upload for debugging includeEventInformation.set(true) } gitLab { // Required for CI status checks (only if using GitLab) projectId.set("..") } } size { // Optional, defaults to 'release' tag.set("release") // Alternatively, use `setFromVariant()` to set the tag from the Android build variant name tag.setFromVariant() // If size tasks/project configuration are enabled. enabled.set(true) } snapshots { // Storage of locally generated snapshots snapshotsStorageDirectory.set("/src/main/snapshots") // Android API version to run snapshots on, must be 29, 31, 33 or 34. apiVersion.set(33) // Include private previews in snapshot generation - defaults to true includePrivatePreviews.set(false) // Optional, snapshots use debug builds, we recommend using a separate tag. tag.set("snapshots") // Alternatively, use `setFromVariant()` to set the tag from the Android build variant name tag.setFromVariant() // If snapshot tasks/project configuration are enabled. enabled.set(true) } reaper { // The build variants Reaper is enabled for. // When Reaper is enabled the application bytecode will be instrumented to support Reaper. enabledVariants.set(listOf("release", "releaseVariant2")) // The key used to identify Reaper reports for your organization. Emerge recommends setting this as an environment variable // Note: This key is not the same as the API key used for uploading to Emerge - you can find this publishableApiKey.set(System.getenv("REAPER_API_TOKEN")) // Optional, defaults to 'release' tag.set("release") // Alternatively, use `setFromVariant()` to set the tag from the Android build variant name tag.setFromVariant() } performance { // Required for performance testing projectPath.set(":perf") // Optional, defaults to 'release' tag.set("release") // Alternatively, use `setFromVariant()` to set the tag from the Android build variant tag.setFromVariant() // If performance tasks/project configuration are enabled. enabled.set(true) } } ``` ### VCS Emerge works best as part of your CI workflow for diffing and comparing size, snapshots and\ performance. To ensure these comparisons are accurate, Emerge leverages VCS information to\ accurately determine the proper comparison builds. **By default, Emerge attempts to set necessary Git values automatically for you.** If you need to override these\ values, you can do so using the `vcs` extension. ```kotlin build.gradle.kts emerge { vcs { sha.set("...") // Optional, will be set automatically using Git information. baseSha.set("...") // Optional, will be set automatically using Git information. branchName.set("my-feature") // Optional, will be set automatically using Git information. prNumber.set("123") // Required for PR status checks & comments, not set automatically. } } ``` ##### Properties | Field | Type | Default | Description | | -------------------------------- | --------- | ----------------------- | ------------------------------------------------------ | | `sha` | `String` | HEAD branch commit sha | The Git sha of the HEAD build. | | `baseSha` | `String` | base branch commit sha | The Git sha of the base build to compare against. | | `previousSha` | `String` | HEAD^ branch commit sha | The git sha of the commit right before the HEAD build. | | `branchName` | `String` | Current branch name | The name of the branch being built. | | `prNumber` | `String` | | The number of the pull request being built. | | `gitHub.repoOwner` | `String` | Repo ID before '/' | The owner of the GitHub repository. | | `gitHub.repoName` | `String` | Repo ID after '/' | The name of the GitHub repository. | | `gitHub.includeEventInformation` | `boolean` | true | Whether to include GitHub event data for debugging. | | `gitLab.projectId` | `String` | | The ID of the GitLab repository. | #### GitHub The GitHub sub-extension can be used to set GitHub-specific values. These are set automatically\ using `repoId` information from git's `remoteUrl` if not specified. These are used for CI integrations, like posting GitHub comments and status checks. ```kotlin build.gradle.kts emerge { vcs { .. gitHub { includeEventInformation.set(true) // Default true, whether to include GitHub event data for debugging. } } } ``` #### GitLab The GitLab sub-extension can be used to set GitLab-specific values. Unlike GitHub values, these\ are not set automatically and will need to be set manually for GitLab CI integration. ```kotlin build.gradle.kts emerge { vcs { .. gitLab { projectId.set("...") // Required for CI status checks (only if using GitLab) } } } ``` ### Size The `size` extension allows you to configure size-specific properties. ```kotlin build.gradle.kts emerge { ... size { tag.set("release") // Optional, tag to use for grouping builds in the Emerge dashboard // Alternatively, use `setFromVariant()` to set the tag from the Android build variant tag.setFromVariant() // If size tasks/project configuration are enabled. enabled.set(true) } } ``` ##### Properties | Field | Type | Default | Description | | --------- | --------- | --------- | ----------------------------------------------------------- | | `tag` | `String` | `release` | The tag to use for grouping builds in the Emerge dashboard. | | `enabled` | `Boolean` | `true` | If size tasks/project configuration are enabled. | ### Snapshots See the [Emerge Snapshots documentation](https://docs.emergetools.com/docs/android-snapshots-v1) for all info on setting up snapshot testing. ```kotlin build.gradle.kts emerge { ... snapshots { // Path to local snapshot image storage, defaults to `/build/emerge/snapshots/outputs` snapshotsStorageDirectory.set("/src/main/snapshots") // Android API version to run snapshots on, must be 29, 31, 33 or 34. apiVersion.set(33) // Include private previews in snapshot generation - defaults to true includePrivatePreviews.set(false) // Tag to use for grouping builds in the Emerge dashboard tag.set("snapshots") // Alternatively, use `setFromVariant()` to set the tag from the Android build variant tag.setFromVariant() // If performance tasks/project configuration are enabled. enabled.set(true) } } ``` ##### Properties | Field | Type | Default | Description | | --------------------------- | --------- | --------------------------------- | ------------------------------------------------------------------------------------------------- | | `snapshotsStorageDirectory` | `String` | `/build/emerge/snapshots/outputs` | Path to local snapshot image storage | | `apiVersion` | `Int` | `34` | The Android API version to use for snapshot generation. Must be an int value in 29, 31, 33 or 34. | | `includePrivatePreviews` | `boolean` | `true` | Include `private` previews in snapshot generation | | `tag` | `String` | `release` | The tag to use for grouping builds in the Emerge dashboard. | | `enabled` | `Boolean` | `true` | If snapshot tasks/project configuration are enabled | ### Reaper The `reaper` extension allows you to configure reaper-specific fields. By default, Reaper will hook into the default `bundle` task for any `enabledVariants` to\ upload the built app to Emerge for detecting all classes. See the [Reaper docs](https://docs.emergetools.com/docs/reaper-setup-android) for more information. ```kotlin build.gradle.kts emerge { ... reaper { // The build variants Reaper is enabled for. // When Reaper is enabled the application bytecode will be instrumented to support Reaper. enabledVariants.set(listOf("release", "releaseVariant2")) // The key used to identify Reaper reports for your organization. Emerge recommends setting this as an environment variable // Note: This key is not the same as the API key used for uploading to Emerge - you can find this publishableApiKey.set(System.getenv("REAPER_API_TOKEN")) // Optional, defaults to 'release' tag.set("release") // Alternatively, use `setFromVariant()` to set the tag from the Android build variant name tag.setFromVariant() } } ``` ##### Properties | Field | Type | Default | Description | | ------------------- | -------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabledVariants` | `List` | | The build variants Reaper is enabled for. | | `publishableApiKey` | `String` | | This key is used to identify Reaper reports sent from your application for your organization. It is safe to include in client-side code. The key can be found at [here](https://emergetools.com/settings?tab=feature-configuration\&cards=reaper_enabled). | | `tag` | `String` | `release` | The tag to use for grouping builds in the Emerge dashboard. | | `enabled` | `Boolean` | `false` | Instruments compiled bytecode to support Reaper and auto-initializes Reaper at runtime. | ### Performance By default, Emerge will automatically add the necessary build configuration needed for the\ specified `projectPath` module. Additionally, the `performance` extension allows you to configure perf-specific properties. ```kotlin build.gradle.kts emerge { ... performance { projectPath.set(":perf") // Required, Module path to the Emerge performance module tag.set("release") // Optional, tag to use for grouping builds in the Emerge dashboard // Alternatively, use `setFromVariant()` to set the tag from the Android build variant tag.setFromVariant() } } ``` ##### Properties | Field | Type | Default | Description | | ------------- | --------- | --------- | ----------------------------------------------------------- | | `projectPath` | `String` | | The module path to the Emerge performance module. | | `tag` | `String` | `release` | The tag to use for grouping builds in the Emerge dashboard. | | `enabled` | `Boolean` | `true` | If performance tasks/project configuration are enabled. | ### Configuration cache support The 2.0 release of the Emerge gradle plugin supports the [Gradle configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html). All future versions are fully compliant. Let us know if you experience a configuration cache violation or open an issue in the [emerge-android repo](https://github.com/EmergeTools/emerge-android). # Migrating from older plugin versions ## 2.X * `buildType` has been removed in favor of `tag`. No functional changes other than naming need to be done to update.