Getting Started with Gradle Enterprise for Gradle users

This guide covers how to get started with Gradle Enterprise, with topics such as strategies for incrementally introducing build scans and Build Cache usage, and key build scan features for improving your development productivity.

Gradle Enterprise provides two complementary functions: Build Scans and the Build Cache. Build Scans are permanent and shareable records of executed builds that allow collaborative troubleshooting and optimization. The Build Cache makes builds faster by allowing reuse of the outputs of builds.

Installation

This guide does not cover installation of Gradle Enterprise. Please consult one of the following installation manuals for help with installation:

The remainder of this guide will assume that your installation has a public hostname of ge.company.com and has enabled HTTPS.

Build Scans

Build scans are a significant innovation in software build tooling. Having centralized and shareable records providing fine-grained details and insights of all builds, including local development builds, enables new levels of collaborative debugging and optimization.

Applying the plugin

Gradle 6.x and later

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

settings.gradle.kts

plugins {
    id("com.gradle.enterprise") version("3.13.3")
}

gradleEnterprise {
    // configuration
}

settings.gradle

plugins {
    id "com.gradle.enterprise" version "3.13.3"
}

gradleEnterprise {
    // configuration
}

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.

The gradleEnterprise extension was added to the root project in version 3.2 of this plugin. Prior to that, the plugin was configured via the buildScan extension of the root project, which is now available as gradleEnterprise.buildScan.

Direct use of buildScan will be deprecated in a later release. Its usage should be replaced with gradleEnterprise.buildScan.

Gradle 5.x

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.

build.gradle.kts

plugins {
  id("com.gradle.build-scan").version("3.13.3")
}

gradleEnterprise {
    // configuration
}

build.gradle

plugins {
  id "com.gradle.build-scan" version "3.13.3"
}

gradleEnterprise {
    // configuration
}

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

Direct use of buildScan will be deprecated in a later release. Its usage should be replaced with gradleEnterprise.buildScan.

You may encounter a warning about an untrusted certificate every time you try to publish a build scan to an HTTPS URL. The ideal solution is for someone to add a valid SSL certificate to the Gradle Enterprise instance, but we recognise that you may not be able to do that. In which case, set the allowUntrustedServer option to true:

Disabling SSL certificate checks

buildScan {
    server = "..."
    allowUntrustedServer = true
}

Disabling SSL certificate checks

buildScan {
    server = '...'
    allowUntrustedServer = true
}

This is a convenient workaround, but you shouldn’t use it as a long-term solution.

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:

Publishing build scan...
https://ge.company.com/s/3z475bz247h5g

Follow that link to view your build scan.

Build scan highlights

This section calls out a subset of the things that you can do with build scans.

Share console logs

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.

Find and view any build scan

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.

View and share test execution results

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.

Only test results from Gradle’s built-in Test task are currently visualized.

Analyze build performance

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.

Optimize cacheability

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.

Compare build scans to find differences

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.

Understand your dependencies

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.

Diagnose incremental build and build caching issues

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.

Trace reused task outputs to their origin

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.

View prior and subsequent builds

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.

Next steps

Always publishing a 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.

Custom tags, values and links

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:

VCS information such as commit identifiers, branch names, etc.
Tags for different types of builds (e.g. CI vs. local)
Links to CI system record of build for CI builds

This adds useful context to your build scans.

Integrating your CI tool

Build scans are passive with regard to the build process. That is, enabling build scans does not affect the outcome or outputs of your build. As such, it is generally safe to simply add the necessary configuration to your projects to enable sending build scans to your Gradle Enterprise installation and check it in to version control, enabling it for all users of the build.

The build scan plugin will not cause build failures, even when there is no connection available to the Gradle Enterprise server when trying to publish.

Jenkins

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 to instrument all CI jobs to publish a Build Scan in a noninvasive manner such that the underlying projects do not need to be modified. This eases the adaption 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.

TeamCity

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:

Bamboo

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:

Build Cache

The best way to improve the execution time of yours builds is by not executing something that was already executed, and just reuse the product of this initial execution. Build caching allows to potentially save a tremendous amount of build time by fetching the outputs of certain task executions, from a previous identical execution. Under the hood, a task is a function that takes some inputs and produces some outputs in a deterministic way. By analyzing the task mechanics and its inputs, Gradle can detect whether a given build tries to execute a given task with the same inputs as a previous execution, and decide to reuse the already produced outputs instead of recomputing them.

Gradle Enterprise provides a centralized Build Cache that can be used to share the results amongst different machines and users.

Quick start

Add the following to your project’s settings file:

settings.gradle.kts

buildCache {
  local {
    isEnabled = false (1)
  }
  remote(gradleEnterprise.buildCache) {
    server = "https://ge.company.com" (2)
    path = "/cache/" (3)
    isPush = true (4)
  }
}

settings.gradle

buildCache {
  local {
    enabled = false (1)
  }
  remote(gradleEnterprise.buildCache) {
    server = "https://ge.company.com" (2)
    path = "/cache/" (3)
    push = true (4)
  }
}

1	Disabling the local Build Cache in order to make the effect of the remote Build Cache more visible
2	The address of the build cache server to use, if not using the built-in build cache of the server specified with `gradleEnterprise` extension
3	The request path for the build cache server. It is generally not necessary to set this value, as the default value used is suitable for the default configuration of Gradle Enterprise build cache nodes (including the built-in build cache).
4	Whether to write to the Build Cache, or just read from it

The above configuration disables the local Build Cache for demonstration purposes. Disabling the local Build Cache is generally not recommended and this should be removed for real usage.

Given the above configuration, you can now run your build with --build-cache.

You may encounter problems with an untrusted SSL certificate when you try to use the Gradle Enterprise Build Cache backend with an HTTPS URL. The ideal solution is for someone to add a valid SSL certificate to the Gradle Enterprise instance, but we recognize that you may not be able to do that. In that case, set the allowUntrustedServer to true:

Disabling SSL certificate checks

buildCache {
  local {
    isEnabled = false
  }
  remote(gradleEnterprise.buildCache) {
    server = "https://ge.company.com"
    path = "/cache/"
    isPush = true
    allowUntrustedServer = true
  }
}

Disabling SSL certificate checks

buildCache {
  local {
    enabled = false
  }
  remote(gradleEnterprise.buildCache) {
    server = "https://ge.company.com"
    path = "/cache/"
    push = true
    allowUntrustedServer = true
  }
}

This is a convenient workaround, but you shouldn’t use it as a long-term solution.

If this is the first time your project is being built while using the remote Build Cache, you will not see any reuse from the Build Cache; only uploads to it. If you run the same build again, you should see output from Gradle indicating that tasks were reused from the Build Cache.

Gradle Enterprise provides an overview of the Build Cache activity at https://ge.company.com/cache-admin, which you can use to see the effect of running your build against the Build Cache.

The exact numbers you see will depend on how many cacheable tasks your build executed. In order for a task to be cacheable, it must be designed with certain considerations and must declare itself to be cacheable. Many of Gradle’s built-in tasks are cacheable, and increasingly many tasks from third-party community plugins are cacheable.

Remote Build Cache nodes

Build Cache nodes are the Build Caches that Gradle builds connect to. Gradle Enterprise provides a built-in node at https://ge.company.com/cache, as we have seen. You can install additional “remote” nodes, potentially on different servers, and connect them with Gradle Enterprise.

Different projects may produce and reuse task outputs at different rates. As Build Caches are limited in size, with least recently used items being evicted to make space, a project that produces many outputs and is frequently changing may undesirably dominate the Build Cache and result in a low cache hit rate for other projects. Distributing projects across Build Cache nodes may yield higher hit rates.

The effectiveness of using a remote Build Cache is largely dictated by the speed of network communication between the build and the Build Cache. Using a Build Cache node that is closer to where the builds are run, or that otherwise has a better network connection to it, may reduce build times by reducing network transfer times.

The Gradle Enterprise Admin Manual details how to install and configure remote nodes.

Configuration

Nodes can be configured by going to https://ge.company.com/cache-admin and navigating to the Nodes page.

In particular, consider increasing the Build Cache size from the default of 1 GiB to something in the 10s of GiB. The larger the Build Cache, the more it can store, which may increase your cache hit rate.

Next steps

Learning more about the Build Cache

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.

Planning a roll out

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.

Getting help or asking questions

If you are currently using Gradle Enterprise, as part of your trial sign-up or license purchase, you will have received instructions on how to access the priority Gradle Enterprise support channel. If you have any issues with or questions about Gradle Enterprise, please raise a support request.

Alternatively, or if you are not yet using Gradle Enterprise, you can use the Gradle discussion forum if you are able to discuss your issue publicly. If you are unable to discuss your issue publicly, please use our contact form.

Keeping up to date

Gradle and Gradle Enterprise are constantly evolving with regular updates that add new features and capabilities. The monthly Gradle newsletter is an easy way to stay informed about new releases, features and Gradle events.