Develocity sbt Plugin User Manual

Apply the Develocity sbt plugin to your build by adding the following configuration block to a new or existing project/plugins.sbt file in your sbt project. The sbt plugin will be downloaded automatically from Maven Central once you load your build.

All Develocity settings are grouped under one configuration object that is recommended to be set in the ThisBuild scope. Unless you intend to publish Build Scans to scans.gradle.com, the minimum configuration required is that of the Develocity server URL.

Other configuration options will be described as we introduce each feature, but you can find all configuration options in the configuration reference.

If your Develocity server uses an SSL certificate that is not trusted by your build’s Java runtime, you will not be able to publish Build Scans without explicitly allowing untrusted servers.

To do this, set the allowUntrusted option to true:

Use of this configuration is a security risk as it makes it easier for a third party to intercept your Build Scan data. It should only be used as a short term workaround until the server can be configured with a trusted certificate.

A free version of Develocity is available at scans.gradle.com, but before you can publish a Build Scan you need to agree to the terms of use, which can be found at https://gradle.com/help/legal-terms-of-use.

You can agree to the terms of use by adding the following configuration to the build:

Once you have accepted the terms of use, you can start publishing Build Scans to scans.gradle.com.

Unlike other build tools, sbt is often used by typing commands in its own interactive shell. In this mode, sbt will publish a Build Scan for each top-level task that it runs.

Once you’ve gone through the initial setup of the previous section, you are ready to start publishing Build Scans. But when should you publish them? Every time you run a build? Only when the build fails? It’s up to you. The Develocity sbt plugin has several options that allow you to use whatever approach works best.

By default, Build Scans are uploaded in the background after the build has finished. This allows the build to finish sooner, but can be problematic in build environments (e.g. ephemeral CI agents) that terminate as soon as the build is finished, as the upload may be terminated before it completes. Background uploading should be disabled for such environments.

Detailed information regarding project-level access control can be found here.

By default, console log messages generated during the build are captured and displayed in Build Scans.

You may want to skip capturing console log messages for security and privacy reasons, such as console log messages that leak sensitive data, or performance and storage reasons, such as tasks that produce a lot of console log messages that are irrelevant for your use of Build Scans.

Console log messages capture can be disabled programmatically via the Develocity configuration object, or via a system property.

To disable programmatically, set the buildLogging option to false:

To disable without modifying the build script, supply the develocity.scan.captureBuildLogging system property to the build. If the property is set to false, capture is disabled. Otherwise, capture is enabled. The system property setting always takes precedence over the programmatic setting.

(sbt plugin 1.1+)

Build Scans capture information on key resources of the machine executing the build. This includes CPU load, memory, disk usage, network activity, and the names of the most CPU-intensive processes. These insights can help analyze poor build performance, whether due to the build needing too many resources or factors external to the build. It can also help understand if the machine is underutilized and if it could do more work.

By default, resource usage is captured and displayed in Build Scans.

You may want to skip capturing resource usage for security/privacy reasons, or because you are unable to upgrade to sbt 1.7.0+. Note that the names of processes external to the build (i.e. not the build process nor its descendants) can be obfuscated.

Resource usage capture can be disabled programmatically, or via a system property.

To disable programmatically, create a copy of the original capture configuration with an updated behavior regarding resource usage capturing:

To disable without modifying the build script, supply the develocity.scan.captureResourceUsage system property to the build. If the property is set to false, capture is disabled. Otherwise, capture is enabled. The system property setting always takes precedence over the programmatic setting.

You can easily include extra custom information in your Build Scans in the form of tags, links and values. This is a very powerful mechanism for capturing and sharing information that is important to your build and development process.

This information can be anything you like. You can tag all builds run by your continuous integration tool with a CI tag. You can capture the name of the environment that the build published to as a value. You can link to the source revision for the build in an online tool such as GitHub. The possibilities are endless.

You can see how the custom data appears in figures 1 and 2:

Develocity allows listing and searching across all of the Build Scans in the system. You can find and filter Build Scans by tags and custom values, in addition to project name, outcome and other properties. In figure 3, for example, we are filtering for all Build Scans that have the tag "CI" and a git branch name of "main":

Develocity sbt plugin captures the state of selected boolean settings and configuration options. These settings and configuration options can have a significant impact on the behavior of the entire build. Monitoring them provides insights into the overall build configuration. The state of the captured settings and configuration options is available via the Build Scan.

All settings are captured at ThisBuild scope.

Build Scans capture certain identifying information such as the operating system username, hostname, network addresses, and CPU-intensive process names. You may choose to obfuscate this data so that it is not decipherable in Build Scans when viewed, by registering obfuscation functions as part of the sbt plugin configuration.

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

Obfuscating the username:

Obfuscating the hostnames:

Obfuscating the IP addresses:

Obfuscating the non build related process names (sbt plugin 1.1+):

sbt supports user-defined custom configuration. By default, the Develocity sbt plugin sets up the Test and IntegrationTest configurations to capture test data.

It is possible to configure the Develocity sbt plugin to capture test data produced in custom configurations as well:

In order to use build caching for sbt, you need to configure the location of your Develocity server.

The precise URL you need depends on the hostname that your Develocity 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 Develocity over HTTPS. The ideal solution is for someone to add a valid SSL certificate to the Develocity instance, but we recognise that you may not be able to do that. In this case, set the allowUntrustedServer option to true:

The Build Cache works based on inputs and outputs. For each supported tasks a cache key is calculated by inspecting all inputs. The cache key is then used to lookup the outputs of that execution in the cache. If no result can be found, the task is executed, and the outputs are stored in the Build Cache under the cache key.

This section explains how inputs can be fine-tuned.

While working with the Build Cache you may encounter situations where build results are not retrieved from the Build Cache, although you would expect them to. This section provides guidance for analyzing and solving these problems.

The Test overview page shows a high level overview of all the tests that were executed as part of the build. The test results are displayed hierarchically: they are grouped by task, test suite and finally test case. Next to each task, test suite and test case, the outcome and the total time are displayed.

The Test suite details page displays the results of the test cases which ran as part of the selected test suite.

Errors that may have happened during the setup or cleanup phase of the test suite execution are reported in this page.

The suite’s overall outcome is broken down into Class setup/cleanup and Test execution outcomes. Class setup/cleanup tracks whether a failure occurred in the suite’s setup / teardown callbacks, and Test execution whether it was a test case that caused the test suite to fail.

At the bottom of the page, the test cases that were executed as part of this test suite are listed, along with the time and outcome of each execution. A test case may be run more than once in case of retries. A test case's duration may be missing in case the test framework did not report it.

Clicking on a test case will open the details for this test case, which will display the results of the executions of this test case.

The Test case details page displays the results of the executions of the selected test case.

The total time and outcome of each execution of the selected test case are displayed on the page. If an execution failed with an exception, then the exception is displayed under the corresponding execution.

Test retry is not enabled by default. It can be enabled and configured via the testRetry field of the develocityConfiguration object. The initialization below shows the default configuration.

By default, all tests are eligible for retrying. The field classesFilter of the test retry configuration can be used to control which tests should be retried and which should not.

The decision to retry a test or not is based on the tests reported class name, regardless of the name of the test case or method. The annotations present or not on this class can also be used as the criteria.

By default, individual tests are retried. The classRetryFilter field of the test retry configuration can be used to control which test classes must be retried as a whole unit. To retry a class as a whole, the class must also satisfy the classRetryFilter predicate.

You may find that local developer builds do not benefit much from retry behaviour, particularly when those tests are invoked via your IDE. In that case, we recommend enabling retry only for CI builds.

The test retry functionality should work with all test frameworks and all sbt versions supported by Develocity. However, some test frameworks support only suite-wide retries: if a test case fails in a test suite, the entire test suite is retried.

Please refer to the compatibility matrix below to learn about possible limitations.

Contact us at support.gradle.com if the testing framework you are using is missing from the above list (or it’s not working).

When using background Build Scan uploading (default behaviour, 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 ~/.sbt/1.0/.develocity/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 ~/.sbt/1.0/.develocity/build-scan-data/<<plugin-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 list below details the notable information captured by the Develocity sbt plugin and transmitted in a Build Scan.

Build Scans published to a Develocity installation are viewable by all users that can reach the server and have the required roles, should Identity Access Management (IAM) be turned on. Develocity provides a search interface for discovering and finding individual Build Scans.

Build Scans published to scans.gradle.com are viewable by anyone with the link assigned when publishing the Build Scan. Links to individual Build Scans are not discoverable and cannot be guessed, but may be shared.

The plugin caches the following tasks out of the box:

By default, Develocity configures Build Caching for compilation and test results in the Compile, Test and IntegrationTest configurations.

If your build defines or uses additional sbt.Configuration, then you will need to add the Develocity Build Cache settings in that configuration:

If your custom configuration extends the Test configuration, then Develocity will automatically inject the settings required for flaky test detection, test retry, etc., along with the settings required to enable Build Caching.

If your custom configuration does not extend the Test configuration, but you still want to inject the settings required for features related to testing, then you can pass the optional argument forceTestSettings = true to the develocitySettings method:

By default, the Build Cache is configured with requireClean = true to allow only clean builds to push to the Build Cache. This behavior can be switched on or off by setting the requireClean property in BuildCache:

When executing compile in a configuration where the Build Cache has been enabled, Develocity will store the result of compilation in a cache, so that they can be reused by subsequent builds.

The cache key for the compile task is computed based on the following inputs:

The cache key for the compile task of a given project and configuration can be seen with:

When executing test, testOnly or testQuick in a configuration where the Build Cache has been enabled, Develocity will store the result of the test execution in a cache, so that they can be reused by subsequent builds.

The cache key for these tasks is computed based on the following inputs:

The cache key for the test task of a given project and configuration can be seen with:

The cache key for the testOnly and testQuick tasks of a given project and configuration can be seen with:

(sbt plugin 1.1+)

In the Develocity sbt plugin 1.1 the following properties were renamed:

If the build is using the old property names, a warning message will be displayed in the build log. To avoid the warning message, update the build to use the new property names.

(sbt plugin 1.1.2+)

In version 1.1.2 of the Develocity sbt plugin, the apply methods used to create various configuration objects were deprecated. Instead of using the apply methods, create new instances from previous values using the respective withXXX methods. Each call to withXXX will create a copy of the configuration object and set the field XXX to the provided value. All other values are taken from the configuration object being accessed.

For example, to disable the background uploading of the Build Scan, the following code should be used to change the backgroundUpload value of the default BuildScan configuration:

Please see the DevelocityConfiguration API reference for more details.

If the build is using apply methods to create configuration objects, a warning message will be displayed in the build log. To avoid the warning message, update the build to modify the default configuration.