Getting Started with Gradle Enterprise for Gradle users

This version of Gradle uses com.gradle.enterprise as the plugin ID. The plugin must be applied in the settings file of the build.

The plugin is configured via the gradleEnterprise extension available in the settings script, which is also available via the root project in project build scripts. The same instance is used for the settings extension and root project extension.

This version of Gradle uses com.gradle.build-scan as the plugin ID. The plugin must be applied to the root project of the build.

The plugin is configured via the gradleEnterprise extension of the root project in project build scripts.

Given the above configuration, you can now run your build with --scan to produce a build scan. As the build completes, the last lines of output will be similar to:

Follow that link to view your build scan.

Build scans include the console output produced by the build. Many tools used by the build, such as compilers, often write diagnostic information to the console log.

Use the left navigation menu to visit the Console log section.

Click on any line to highlight it or shift-click two different lines to highlight a block of lines. Note that the browser’s current location has been updated. By sharing that URL with a colleague, you can direct them to the exact console output that you wish them to see.

Many aspects of build scans are directly linkable in order to facilitate sharing and collaboration.

Search through all the published build scans by going to https://ge.company.com.

This view allows searching by various criteria, including root project name, user name, build outcome, build start time and more. By default, the list is sorted to show the most recent scans first.

Beyond looking for a particular build scan, the listing can provide new insights into the actual builds being run at your organization and by your colleagues. You may find occurrences of previously unknown errors with your build, or that the build is taking longer in certain cases than you expected, or that certain build users are executing more tasks than they need to and are therefore subjecting themselves to more build time than they need to, and other previously unknown behaviors.

Tests are the cornerstone of software development. Build scans visualize test results, including test durations, logging output and outcome.

Use the left navigation menu to visit the Tests section. Click on any failed test to see the console output and error trace.

Developers can effortlessly share test results of local builds with colleagues via build scans, making solving test failures collaboratively more efficient.

A key benefit of build scans are the various insights they provide into build performance. Many builds provide different functions for different people and will perform differently on different machines. Having deep performance insights available for every build enables optimizing all corners of the build, for all users.

Use the left navigation menu to visit the Performance section.

The different tabs focus on different aspects of performance, with the first Build tab providing a high level build time breakdown and memory information.

The Configuration tab provides an interactive breakdown of the time spent configuring the projects participating in the build, highlighting the slowest scripts, plugins and lifecycle callbacks used during the build. The slowest scripts, plugins and lifecycle callbacks are typically the best candidates for optimizing in order to make your build faster.

The Dependency resolution tab provides insights into how much time was spent during dependency resolution. It also shows which dependencies have been resolved during configuration time or execution time.

The Task execution tab provides a concise breakdown of the tasks that participated in the build, grouped by outcome. This provides a high level view of task execution and can be used to understand incremental build and build caching coverage for a particular build. The dedicated Timeline section (available via the left navigation menu) provides an alternative view, visualizing the task execution as a timeline. This view provides more detail on individual tasks (click the task name in the list), and more clearly shows the parallel utilization of your build.

The Build Cache tab displays the Build Cache configuration for the build (e.g. whether a remote Build Cache was used), and lists the individual Build Cache operations and how long they took. This is particularly useful for analyzing the performance of the remote Build Cache connection and identifying whether a slow connection is having adverse effects on the build time.

The Daemon tab displays information about the Gradle daemon, e.g. age of the daemon used to run the build.

The Network activity tab lists the network requests made during the build and can be used to identify slow dependency repositories or particularly troublesome requests.

For a task to be cacheable, its implementation must meet certain requirements along with its configuration. Build scans make it easy to see which tasks are cacheable, and why those that aren’t, aren’t.

The Timeline section allows filtering of tasks via certain criteria, one of which is cacheability.

This is useful when starting with build caching, and as your projects change and evolve, to ensure that you are getting the most out of the Build Cache.

Gradle Enterprise provides the ability to compare aspects of two build scans, including the inputs into the executed tasks, the resolved dependencies, what switches the builds were invoked with and aspects of the build infrastructure such as the environment where the builds were run.

To compare two scans, use the scan list to find the scans to compare, selecting them by clicking the respective or icon. Or, from a scan that you wish to compare with another, click the Compare Build Scan on the left navigation menu.

Each build scan provides an interactive visualization of every dependency configuration resolved during that build. You can search for dependencies across all projects within the build by name, and also by types of resolution such as dynamic version resolutions.

Dependency comparison shows the differences in the resolved dependency configurations between two builds. This is useful for highlighting unanticipated changes, and as the entire graph is compared including transitive dependencies, visualizing the full impact of a change.

The task inputs comparison is particularly effective in helping diagnose issues with incremental build and build caching, particularly cases where reuse was expected but didn’t occur. In such cases, it is common that a non-obvious input has actually changed which is preventing reuse. By comparing the inputs of the task from the builds where reuse was expected, the exact input property with a different value between the builds is immediately apparent.

When task outputs are reused in a build, due to incremental build or build caching, the build scan for that build provides links to the build scan of the origin build.

This feature can be used to provide an audit trail of build outputs, and for validating reuse. It is particularly useful for identifying and diagnosing incorrect reuse, which is typically caused by under declaration of task inputs. In such cases, the build scan for the origin build can be used to determine the actual input state for cross referencing with the build scan that incorrectly reused the outputs.

To see this feature in action, create two build scans where one reuses output from another. The simplest way to do this is by running exactly the same build twice. View the build scan for the subsequent build and open the timeline visualization. Click on the name of any task that was UP-TO-DATE, and click the View origin Build Scan link to view the build scan for the build that produced the reused outputs.

From a build scan, you can easily navigate to prior or subsequent builds from the same root project directory. This equates to builds of the same project for a particular user on a particular machine. For example, when running two builds consecutively for the same project, from either build scan you can easily navigate to the other.

To see this feature in action, create two build scans from the same project. From either build scan, click the See before and after link in the left navigation menu. The builds that happened before and after the current build are shown and can be clicked to open the corresponding build scan.

The build scan plugin can be configured to publish a build scan for every build invocation, or, always publishing if certain programmatically defined criteria are met, or, always publishing if the build fails. The dedicated Gradle Enterprise Gradle Plugin User Manual provides a section outlining how to do this.

It is strongly recommended to configure your builds to always publish build scans, for every build. Collecting build scans for every build yields deeper visibility and insights into how your build is performing and is being used, as well as making features such as tracing reused task outputs more effective.

Build scans can be enriched with metadata particular to your environment, by using an API provided by the build scan plugin.

Extending your build scans with tags, values and links is strongly recommended. In particular:

This adds useful context to your build scans.

The Gradle Jenkins plugin prominently displays links to the Build Scan for any Gradle or Maven build that produce build scans, which makes it convenient to access the build scans. See the following screenshot for an example:

Besides that, the plugin allows you to instrument all CI jobs and to publish a Build Scan without modifying the underlying projects. This eases the adoption of build scans within the company and allows configuring the Gradle Enterprise Gradle plugin or Gradle Enterprise Maven extension in a central place. For more information please read the documentation here.

The TeamCity Build Scan plugin prominently displays links to the Build Scan for any Gradle or Maven build that produce build scans, which makes it convenient to access the build scans. See the following screenshot for an example:

Besides that, the plugin allows you to instrument all CI jobs and to publish a Build Scan without modifying the underlying projects. This eases the adoption of build scans within the company and allows configuring the Gradle Enterprise Gradle plugin or Gradle Enterprise Maven extension in a central place. For more information please read the documentation here.

The Gradle Enterprise Bamboo plugin prominently displays links to the Build Scan for any Gradle or Maven build that produce build scans, which makes it convenient to access the build scans. See the following screenshot for an example:

Besides that, the plugin allows you to instrument all CI jobs and to publish a Build Scan without modifying the underlying projects. This eases the adoption of build scans within the company and allows configuring the Gradle Enterprise Gradle plugin or Gradle Enterprise Maven extension in a central place. For more information please read the documentation here.

The Gradle Enterprise GitLab templates allow to instrument CI jobs and to publish a Build Scan without modifying the project’s build scripts. This eases the adoption of build scans within the company and allows configuring the Gradle Enterprise Gradle plugin or Gradle Enterprise Maven extension at the CI level. See the following snippet for an example:

For more information please read the documentation here.

The Gradle GitHub Action prominently displays links to the Build Scan for any Gradle build that produce build scans, which makes it convenient to access the build scans. See the following screenshot for an example:

Besides that, the plugin allows you to instrument all CI jobs and to publish a Build Scan without modifying the underlying Gradle build, via environment variables defined in your GitHub Actions workflow. This eases the adoption of build scans within the company and allows configuring the Gradle Enterprise Gradle plugin at the CI level. For more information please read the documentation here.

Reading the dedicated Build Cache Guide is strongly recommended. This guide provides detailed information about build caching in general, including considerations for using it in practice. It also covers how to debug and optimize Build Cache usage using build scans.

The best roll out strategy depends on your circumstances. A common strategy however is to first enable Build Cache usage only for CI builds, then later enabling for local development builds. The Build Cache configuration within a build can be specified dynamically, supporting this kind of usage. Examples of different kinds of configuration patterns are available in the Gradle User Guide.

Enabling build scans for any build using the remote Build Cache should be considered a prerequisite. Build scan insights make it considerably easier to debug and optimize Build Cache usage.