Gradle Enterprise Maven Extension User Manual

When you publish build scans to a Gradle Enterprise instance, you must configure the location of the Gradle Enterprise server.

The precise URL you need depends on the hostname that your Gradle Enterprise instance has been configured with. If in doubt, be sure to ask whomever manages that instance.

You may encounter a warning about an untrusted certificate when connecting to Gradle Enterprise over HTTPS. 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 this case, set the allowUntrusted option to true:

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

In order to publish to scans.gradle.com, you need to accept the terms of service.

Be sure to check the terms of service at the URL shown in the above fragment.

Once you have accepted the terms of service, you can start publishing build scans to scans.gradle.com.

This is the default. There are many advantages to publishing build scans regularly, such as being able to track the behavior and performance of a build over time. It makes no sense relying on ad-hoc publishing of scans in such a situation as it’s easy to forget on the command line. Should you decide to explicitly enforce this default option, you can do this as follows:

This approach means that you get a build scan for every successful and failed build that runs, including from your continuous integration infrastructure and your developers.

If you want to deactivate build scans for a particular build, you can pass the -Dscan=false system property to Maven.

We imagine that when you first start experimenting with build scans, you won’t want to publish them all the time until you become familiar with the implications. Even then, you may have good reason not to go all-in and automate the process. That’s where one-off build scans come in.

If you only want to publish build scans when explicitly requested, use the following option:

Many of you will want a bit more control over exactly when build scans are published without resorting to using -Dscan each time. Perhaps you only want to publish build scans when the build fails, or if the build is running on your continuous integration infrastructure. Such scenarios are covered by the options in the following table.

Giving a more concrete example, let’s say you only want to publish build scans from your CI system, which is identified by having a CI environment variable. This configuration will do the trick:

The easiest way to configure a build environment to authenticate with Gradle Enterprise is to use the the following goal:

When executed, it opens your web browser and asks to confirm provisioning of a new access key. You will be asked to sign in to Gradle Enterprise in your browser first if you are not already signed in.

When confirmed, a new access key will be generated and stored in the .gradle-enterprise/keys.properties file within the Maven user home directory (~/.m2 by default).

Any existing access key for the same server will be replaced in the file, but will not be revoked at the server for use elsewhere. To revoke old access keys, sign in to Gradle Enterprise and access “My settings” via the user menu at the top right of the page.

Access keys can also be configured manually for an environment, when automated provisioning is not suitable.

Capturing goal input files increases the amount of data transmitted to the build scan server at the end of the build. If the network connection to the build scan server is poor, it may increase the time required to transmit. Additionally, it may also increase the data storage requirements for the build scan server.

This data is currently only used for build comparison, which is only available in Gradle Enterprise and is not available with scans.gradle.com. If you are using scans.gradle.com, it is not recommended that you enable capture of goal input files.

If you are using Gradle Enterprise and utilising its build cache to accelerate your builds, it is strongly recommended to enable capture of goal input files as identifying which files have changed between builds with build comparison is extremely effective for diagnosing unexpected build cache misses.

Goal input files capture can be enabled programmatically, via a system property, or via the gradle-enterprise.xml configuration file.

Tags are typically used to indicate the type or class of a build, or a key characteristic. They are prominent in the user interface and quickly inform a user about the nature of a build. A build can have zero or more tags.

Note that the order in which you declare the tags doesn’t affect the build scan view. They are displayed in alphabetical order, with any all-caps labels displayed before the rest.

You can see the effect of a custom tag in figure 2.

Builds rarely live in isolation. Where does the project source live? Is there online documentation for the project? Where can you find the project’s issue tracker? If these exist and have a URL, you can add them to the build scan.

Links can also be added in your project POM.

The <name> is simply a string identifier that you choose and that means something to you.

You can see the effect of a custom link in figure 2, which shows how a label CVS becomes a hyperlink that anyone viewing the build scan can follow.

Some information just isn’t useful without context. What does "1G" mean? You might guess that it represents 1 gigabyte, but of what? It’s only when you attach the label "Max heap size for build" that it makes sense. The same applies to git commit IDs, for example, which could be interpreted as some other checksum without a suitable label.

Custom values are designed for these cases that require context. They’re standard key-value pairs, in which the key is a string label of your choosing and the values are also strings, often evaluated from the build environment.

As with tags, you can filter build scans by custom values in Gradle Enterprise.

(Maven extension v1.2+)

What if you want to execute some code based on data that is only available late in the build? For example, you might want to label a build as "built-from-clean" if the clean goal was run. But you don’t know if that’s the case until the goal execution plan is ready.

The Maven extension provides a buildFinished() hook that you can use for these situations. It defers attaching custom data until the build has finished running. As an example, imagine you want to report how much disk space was taken up by the output directory. The build doesn’t know this until it’s finished, so the solution is to calculate the disk space and attach it to a custom value in the buildFinished() hook:

The buildFinished() action has access to a BuildResult instance that you can use to determine whether the build failed or not, like so:

(Maven extension v1.2+)

You might want to perform a custom operation when a build scan is published, like notifying an internal tool of your company. To do this , you can use the BuildScanApi#buildScanPublished() method:

(Maven extension v1.2+)

Some data that you may wish to add to your build scan can be expensive to capture. For example, capturing the Git commit ID may require executing the git command as an external process, which is expensive. To do this without slowing your build down, you can use the BuildScanApi#background() method:

This method takes a function that will be executed on a separate thread, which allows Maven to continue without waiting for the expensive work to complete.

All background work will be completed before finishing the build and publishing the build scan.

Any errors that are thrown by the background action will be logged and captured in the build scan.

See the BuildScanApi#background() API reference for more information.

(Maven extension v1.2.3+)

You may want to ensure that a given operation is only executed once for the whole execution of a multi-project Maven build.

The Maven extension provides an executeOnce() hook that you can use for these situations. It must be provided with an identifier, and can call any service provided by the API. The identifier is used to guarantee that the provided action will be executed at most once.

(Maven extension v1.3.1+)

Build scans capture certain identifying information such as the operating system username, hostname and network addresses. You may choose to obfuscate this data so that it is not decipherable in build scans when viewed. To do this, you can use the BuildScanApi#obfuscation() method.

With Maven extension v1.6.3+, you can register obfuscation values on the gradle-enterprise.xml. These will always be applied, even in case of very early build failures, that would prevent programmatic configuration via the BuildScan API. If the BuildScan API gets eventually called, obfuscation functions registered with it will have precedence over the values defined via XML.

The following examples show registering obfuscation functions for the different identifying data.

See the BuildScanApi#obfuscation() API reference for more information.

When using background build scan uploading (default behaviour since Maven extension version 1.5, see this section for configuration options) upload failures are not visible in the build logging due to occurring in a background process after the build has finished. Instead, errors are logged to a file located at ~/.m2/.gradle-enterprise/build-scan-data/upload-failure.log. If this additional information does not help to resolve the failure, please contact technical support and include the contents of this log file.

If the background upload process fails to start, a warning is shown in the build console and uploading is performed in the build process. If this occurs, please contact technical support with the log files located at ~/.m2/.gradle-enterprise/build-scan-data/<<extension-version>>/pending-uploads/*.log.

Build scans attempt to determine the host name of the machine. An issue affecting macOS can cause a delay when doing this in some environments.

If you see a warning during your build that resolving the local host name is slow, you can workaround the problem by adding a host name mapping to your /etc/hosts file.

Add these lines to your /etc/hosts file, substituting your computer name for 'mbpro' in the below snippet:

The extension uses a local build cache to store build outputs in the local filesystem. It prevents network roundtrips by storing both outputs that local builds created, as well as outputs that were downloaded from the remote build cache.

Gradle Enterprise provides a cache node that is built into the server. Additionally, remote cache nodes can be spun up and connected to the server. By default, the built-in cache node of the Gradle Enterprise server is used.

The following snippet shows you how to ignore any file called META-INF/build.properties on any runtime classpath in the given project. You can share this setting across many projects by putting it in the pluginManagement section of your parent POM. You can use ANT-style patterns like META-INF/**/*.sql as well.

(Maven extension 1.8+)

Since properties files are a common file format to store data generated by the build, the normalization DSL provides special support for ignoring specific entries in properties files. Again, ANT-style patterns can be used to match relevant properties files. In the following example any files named build.properties in com/example or any subdirectory are matched and the value of the property build.timestamp is ignored:

A common location to store properties files is the META-INF directory. Thus, the normalization DSL provides a shortcut for normalizing files matching META-INF/**/*.properties

(Maven extension 1.8+)

The <metaInf> configuration element offers even more convenience configuration settings for normalizing the contents of the META-INF directory. For example, you may only want to ignore one or more attributes in MANIFEST files, e.g. Implementation-Version instead of ignoring the whole file. This can be done as follows:

If you want to ignore MANIFEST files completely there’s the <ignoreManifest> configuration as a shorthand for that. It’s the equivalent of adding META-INF/MANIFEST.MF as an ignored file.

In situations where you have several changing files in the META-INF directory, you might want to ignore the contents of that directory completely. The <ignoreCompletely> configuration is a shorthand for adding META-INF/** to ignored files.

The predefined inputs and outputs of any supported goal can be augmented by declaring them in the <pluginManagement> section of your pom.xml file. A common use case for declaring additional input files are test cases that read from a location that is not automatically tracked. For example, you might have Cucumber specification files located in the src/test/specs directory. Any change to the files in that directory may change the result of running the tests. So changing specification files should result in rerunning the tests and not loading the results from the cache. Without additional configuration the build cache is unaware of these additional inputs and will therefore load the result from the cache even if specification files change.

You can disable caching on a fine-grained level in the <pluginManagement> section of your pom.xml file. The following will disable caching for all executions of the failsafe plugin in the given project:

You can also disable caching for a specific execution. Other executions of that plugin will then still remain cacheable. The following will disable caching only for the systems-integration-test execution of the failsafe plugin. Other tests will remain cacheable.

The extension allows you to make any goal cacheable, beyond the ones that are supported out of the box. Take great care to define all of the goal’s inputs and outputs before doing so, to avoid false cache hits and follow-up errors.

When making goals cacheable, you don’t need to repeat the values of all their inputs and outputs. You can simply provide the name of each property and the extension will look up the value in the goal’s configuration. The extension will make sure that you have handled all configuration parameters of the goal in this way. If some parameter is irrelevant for the purposes of caching, e.g. because it only affects console output, you can tell the extension to ignore it.

For input properties, the extension supports all primitives, Strings, Enums and Collections, Arrays and Maps of those. Any other types need to be broken down using the nestedProperties (for a single complex type) or iteratedProperties (for a Collection of complex types) configuration.

The extension provides several loggers to make analyzing problems with build caching easier. To show the effective cache configuration, use the gradle.goal.cache logger:

The gradle.goal.cache logger will also print the result of determining the cacheability of the executed goals:

Sometimes you might encounter a situation where a goal execution is not avoided by using the cache although you would expect it to be. For example, if you run the same build twice without any changes, the outputs of all supported goals should be retrieved from the local build cache (if it is enabled). If this is not the case, this almost always is caused by unstable inputs, e.g. a timestamp being added to a file by some build logic. In order to identify which inputs change between builds the Maven build comparison feature can be used. Simply run the same Maven build twice and compare those two builds. To make it easier to find unstable input files capturing of goal input files should be explicitly enabled using -Dgradle.scan.captureGoalInputFiles=true

Once the build scans have been published they can be compared in Gradle Enterprise. In this example, the build was configured to write a timestamp to the build.properties file. When comparing the two builds this shows up nicely in the comparison.

Once the changing input is identified, the build can be changed to be reproducable or normalization can be used to ignore the changing input.

Some widely used Maven plugins are a common cause of cache misses because they produce changing build results. This chapter shows you how to solve them.

Consideration must be given to any supporting resources required by tests.

Test distribution takes your tests and executes them on remote agents. The test runtime classpath and any additionally declared file inputs are transferred to the agents. If your tests are expecting any other resources to be locally available, such as a running database, the test agents must also provide the resource or the tests will fail.

There are two possible approaches to using such resources in your tests:

The first approach is recommended where possible as it is more portable and minimizes the need to change agent environments when test resources change. The Testcontainers project provides an easy way to utilize Docker containers within tests.

When using the second approach of having the agent environment provide resources, it is important to declare the requirements of tests so that appropriate agents that provide the capability can be assigned.

Test distribution is enabled and configured per goal, via the distribution element in the POM.

Tests can be executed by local and/or remote executors.

By default, the number of local executors is derived from the forkCount parameter of the goal. To limit the use of local executors, configure the maxLocalExecutors parameter. Setting it to zero, causes tests to be only executed remotely.

By default, test execution uses as many remote executors as possible. To limit the number used, you can configure the maxRemoteExecutors parameter:

Each test goal will request at most maxRemoteExecutors (or as many as possible if not set) and test goals that are running in parallel will each request their respective configured number of remote executors. So a build running two test goals in parallel each having maxRemoteExecutors set to 10 will request 20 remote executors. The number of remote executors actually used is subject to agent availability and the number of test partitions.

Setting the number of remote executors to zero causes tests to be only executed locally.

Test goals can specify requirements that agents must fulfill in order to be considered compatible. Requirements are matched against the advertised capabilities of the agents that are connected to your Gradle Enterprise server. Only agents that fulfill all requirements are considered compatible. Local executors are assumed to provide all required capabilities. This means that local executors will always be used regardless of the declared requirements, unless use of local executors is disabled.

Requirements are strings that may only contain alphanumeric characters, dashes, underscores, periods, and a single equals sign. It is recommended to use a key-value form (e.g. os=linux) or tag-like form (e.g. postgres) to model requirements.

To ensure tests are executed using the intended Java version, an implicit jdk=«version» requirement is added to the set of declared requirements for the goal. The version is determined from the Java executable set on the goal. Only the major version is taken into account (e.g. jdk=8 for Java 8 and jdk=11 for Java 11).

Test distribution relies on external services in order to execute your build, such as the Gradle Enterprise server and assigned remote agents. When an agent disconnects during the build, the extension reschedules the affected test partition on another local or remote executor. Similarly, when the connection to the Gradle Enterprise server is closed unexpectedly, the extension attempts to reconnect and reschedules the affected test partitions. However, in cases test execution cannot progress, e.g. if local executors are disabled and reconnection attempts are not successful, the extension will fail the build after a configurable wait timeout (30 seconds by default) has elapsed in order to prevent the build from blocking indefinitely.

All well-known and manually declared inputs of the test goal are tracked by test distribution and will be transferred to remote executors. In order to add additional input files that are required for your tests declare them using in the POM configuration of the Gradle Enterprise Maven extension:

Tests may produce file outputs, such as reports. After finishing execution of a test partition all output files that are registered on the test goal are transferred back from remote executors to the build. Test reports and JaCoCo coverage data are automatically tracked.

In addition to the above configuration parameters, the Gradle Enterprise Maven extension respects most of the goal’s configuration. The following parameters influence test partitioning and the type and number of used local and remote executors.

Test distribution is compatible with JaCoCo Maven plugin. Coverage information from all executors, including remote, are merged to produce a single coverage report. No additional configuration is required.

The build log contains information about the test executor used and the partition number for every test class. This information can help if the failure is caused by the test executor, such as a remote agent not providing a required resource.

Executors starting with localhost- are the local executors. All other executors (in our example containing distribution-agent) are the remote executors.

Moreover, the information is persisted in the generated XML reports. However, it is currently not visible in build scans.

Each test partition executes in a separate JVM. If tests share state via static variables, intentionally or unintentionally, they may not work reliably when distributed. They are also unlikely to work reliably when not using test distribution if using forkCount to execute tests in parallel locally.

If your tests already set reuseForks = false to mitigate shared static state, they will likely work reliably with test distribution but be slower to execute than they otherwise would be. This setting causes a partition to be created per test class, which creates additional overhead when there are many test classes.

To make optimal use of test distribution, each test class should be independent of any other test class and not mutate any shared static state. If that is not possible, consider separating test classes that are self-contained from those that aren’t into separate test goals and configuring them accordingly.

Some tests access test resource files in their source location, e.g. in src/test/resources. This location is not an input to the test goal and files will not be available when tests are executed remotely. The maven-resources-plugin copies these files target/test-classes before executing tests. This location is declared as an input, and is part of the test runtime classpath.

One potential solution is to access such files from their location in the target folder instead. However, this does not work in IDEs that don’t delegate test execution to Maven as they use src/test/resources as an input. If you are unable to use Maven for all test execution, a better solution is to access the resource via the runtime classpath via Java’s classpath resource loading mechanism.

If you need to prepare/cleanup resources, start/stop a server etc. before/after your tests are executed, you can implement a JUnit Platform TestExecutionListener.

A custom listener that starts an HTTP server before executing the first test and stops it after the last test has been executed, could look like this:

This sample uses the HTTP server implementation from the jdk.httpserver module that comes with the JDK but would work similarly with any other server or resource. In order for the listener to be picked up by JUnit Platform, you need to register it as a service by adding a resource file with the following name and contents to your test runtime classpath (e.g. by adding the file to src/test/resources):

You can now use the resource from your test:

The gradle-enterprise.xml configuration file supports two types of expressions that are evaluated when reading the configuration file:

For both expression types, the following objects can be referenced:

In addition, the following objects and functions can be referenced in SpEL expressions:

The following example shows how to use both expression types to configure local and CI builds with a single gradle-enterprise.xml file. It uses the JENKINS_URL environment variable (which is present in builds on Jenkins) to determine whether the build is running locally or on CI. Based on that, it enables the local build cache and background build scan upload only for local builds but enables writing to the remote build cache only for CI builds. Moreover, it determines the URL of the remote build cache based on the fictional REGION environment variable. Lastly, it uses Maven-style expressions to configure the remote build cache credentials based on custom environment variables that are typically injected by the CI server.

Unless there are annotation processors on the classpath, the extension uses compile avoidance so your sources are only recompiled if the signatures of the classes on the compile classpath have changed.