The Develocity sbt plugin improves your development workflow and your productivity, when developing and maintaining sbt builds. The plugin enables Build Scan insights and supports publishing to scans.gradle.com.

To publish sbt Build Scans, Develocity version 2023.2+ is required. This manual is optimized for Develocity version 2024.1+ with Develocity sbt plugin version 1.0+.

sbt Build Scan functionality is not enabled by default with Develocity. If you wish to use sbt with Develocity, please contact your customer success representative.

Getting set up

The latest version of the Develocity sbt plugin is 1.1.1 and is compatible with sbt 1.6.0 and all versions above.

The instructions in this section describe applying and configuring the plugin for a single sbt project.

Applying the plugin

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.

project/plugins.sbt
addSbtPlugin("com.gradle" % "sbt-develocity" % "1.1.1")

Connecting to Develocity

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.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://develocity.mycompany.com"))
    )
}

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

Allowing untrusted SSL communication

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:

Disabling SSL certificate checks
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://develocity.mycompany.com"))
        .withAllowUntrusted(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.

Authenticating

Develocity installations may be configured to require Build Scan publishing to be authenticated. Additionally, installations may be configured to only allow certain users to publish Build Scans. If your instance doesn’t require authentication, you can skip to Using Build Scan

Develocity access keys should be treated with the same secrecy as passwords. They are used to authorize access to Develocity from a build.

Automated access key provisioning

The easiest way to configure a build environment to authenticate with Develocity is to use the develocityProvisionAccessKey task.

$ sbt develocityProvisionAccessKey

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 Develocity in your browser first if you are not already signed in.

When confirmed, a new access key will be generated and stored in the keys.properties file within the Develocity storage directory (~/.sbt/1.0/.develocity 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 Develocity and access “My settings” via the user menu at the top right of the page.

If your browser cannot be opened automatically at the correct page, you will be asked to manually open a link provided in the build console.

Manual access key configuration

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

Creating access keys

To create a new access key, sign in to Develocity and access “My settings” via the user menu at the top right of the page. From there, use the “Access keys” section to generate an access key.

The access key value should then be copied and configured in your build environment via file, environment variable or the settings file.

Via file

Develocity access keys are stored inside the Develocity storage directory user home directory (~/.sbt/1.0/.develocity by default), at keys.properties, in a Java properties file. The property name refers to the host name of the server, and the value is the access key.

develocity.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq

The file may contain multiple entries. The first entry for a given host value will be used.

Via environment variable

The access key may also be specified via the DEVELOCITY_ACCESS_KEY environment variable. This is typically more suitable for CI build environments.

The environment variable value format is «server host name»=«access key».

$ export DEVELOCITY_ACCESS_KEY=develocity.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq && \
  sbt compile

The server host name is specified in order to prevent the access key being transmitted to a different server than intended. In the rare case that you require access keys for multiple servers, you can specify multiple entries separated by semicolons.

$ export DEVELOCITY_ACCESS_KEY=develocity1.mycompany.com=7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq;develocity2.mycompany.com=9y4agfiubqqjea4vonghohvuyra5bnvszop4asbqee3m3sm67w5k && \
  sbt compile
Via configuration

You can also specify the access key in your build file:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://develocity.mycompany.com"))
        .withAccessKey("7w5kbqqjea4vonghohvuyra5bnvszop4asbqee3m3sm6dbjdudtq")
    )
}
Short-lived access tokens

Develocity access keys are long-lived, creating risks if they are leaked. To avoid this, users can use short-lived access tokens to authenticate with Develocity. Access tokens can be used wherever an access key would be used. Access tokens are only valid for the Develocity instance that created them.

Develocity server version 2024.1+ supports access tokens.
Changing a Develocity instance’s hostname will cause all existing access tokens to become invalid.

To create an access token:

  1. Get an access key or access token for the user you wish to create a token for.

  2. Decide which permissions the new access token should have.

  3. If project-level access control is enabled, decide which projects the new access token should be able to access.

  4. Decide how long the new access token should live.

  5. Make a POST request to /api/auth/token, optionally with the following parameters. The response will be the access token.

    1. A permissions= query parameter with the config values of each permission you wish to grant. By default, all permissions for the credential used to authenticate the token request are granted to the created token.

    2. If project-level access control is enabled, a projectIds= query parameter with the ID of each project you wish to grant access to. By default, all projects for the credential used to authenticate the token request are granted to the created token.

    3. An expiresInHours= query parameter with the token’s intended lifetime in hours, with a maximum of 24. The default is two hours, or the remaining lifetime of the credential used to authenticate the request, whichever is smaller.

The requested permissions and project ids can be specified as comma-seperated lists or repeated parameters. For example, ?projectIds=a,b&projectIds=c is valid and will request projects a, b, and c.

If project-level access control is not enabled, all access tokens will be granted the “Access all data without an associated project” permission even if it is not explicitly requested.

If the user creating the token does not have one of the requested permissions or projects, Develocity will respond with a 403 Forbidden error. If an access token is used to authenticate the creation request, its permissions and projects will be used for this check instead of the user’s. The request will also error if the requested lifetime would cause the new access token to expire after the one used to authenticate the request. Together, this means you cannot create an access token with more access or a later expiration than the credentials used to authenticate the request.

See the API documentation for more details on the /api/auth/token endpoint.

Here is an example using CURL to create an access token:

$ curl -X POST https://ge.mycompany.com/api/auth/token?permissions=publishScan,writeCache,accessDataWithoutAssociatedProject&projectIds=project-a,project-b&expiresInHours=1 \
    -H "Authorization: Bearer 7asejatf24zun43yshqufp7qi4ovcefxpykbwzqbzilcpwzb52ja"

eyJraWQiOiJ0ZXN0LWtleSIsImFsZyI6IlJTMjU2IiwidHlwIjoiSldUIn0.eyJpc19hbm9ueW1vdXMiOmZhbHNlLCJwZXJtaXNzaW9ucyI6WyJSRUFEX1ZFUlNJT04iLCJFWFBPUlRfREFUQSIsIkFDQ0VTU19EQVRBX1dJVEhPVVRfQVNTT0NJQVRFRF9QUk9KRUNUIl0sInByb2plY3RzIjp7ImEiOjEsImIiOjJ9LCJ1c2VyX2lkIjoic29tZS1pZCIsInVzZXJuYW1lIjoidGVzdCIsImZpcnN0X25hbWUiOiJhIiwibGFzdF9uYW1lIjoidXNlciIsImVtYWlsIjoiYkBncmFkbGUuY29tIiwic3ViIjoidGVzdCIsImV4cCI6NzIwMCwibmJmIjowLCJpYXQiOjAsImF1ZCI6ImV4YW1wbGUuZ3JhZGxlLmNvbSIsImlzcyI6ImV4YW1wbGUuZ3JhZGxlLmNvbSIsInRva2VuX3R5cGUiOiJhY2Nlc3NfdG9rZW4ifQ.H1_NEG1xuleP-WIAY_uvSmdd2o7i_-Ko3qhlo04zvCgrElJe7_F5jNuqsyDfnb5hvKlOe5UKG_7QPTgY9-3pFQ

The resulting token would have the following permissions:

  • “Publish Build Scans”

  • “Read and write Build Cache data”

  • “Access all data without an associated project”

And it would have access to these projects:

  • “project-a”

  • “project-b”

The token would only be usable for one hour.

Connecting to scans.gradle.com

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:

Agreeing to the terms of use
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withTermsOfUse(url("https://gradle.com/help/legal-terms-of-use") -> true)
    )
}

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

Be careful not to commit agreement to the terms of use into a project that may be built by others.

Using Build Scan

Build Scan® is a shareable record of what happened during a build, captured and visualized by Develocity.

What is part of a single Build Scan?

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.

Interactive mode

For example, when invoking a single command in the shell:

sbt:test-project> compile
[info] compiling 1 Scala source to test-project/core/target/scala-2.13/classes ...
[info] compiling 1 Scala source to test-project/backend/target/scala-2.13/classes ..
[info] Publishing build scan...
[info] https://develocity.mycompany.com/s/ohd4cybh6yc4g

sbt allows one to chain several commands separated by semicolons, as in compile; test. In this case, a Build Scan is published for each one of them:

sbt:test-project> compile; test
[info] compiling 1 Scala source to test-project/core/target/scala-2.13/classes ...
[info] compiling 1 Scala source to test-project/backend/target/scala-2.13/classes ...
[success] Total time: 1 s, completed 23 Jun 2023, 15:16:51
[info] Publishing build scan...
[info] https://develocity.mycompany.com/s/lmzvnpyy66vbw
[info] compiling 2 Scala sources to test-project/core/target/scala-2.13/test-classes ...
...
[info] Publishing build scan...
[info] https://develocity.mycompany.com/s/pg37gbjxr4sxo

Batch mode

When sbt is invoked with several tasks on the command line, as it’s often the case on CI, sbt will publish a single Build Scan for the whole sbt process.

$ sbt compile test
[info] welcome to sbt 1.9.0 (BellSoft Java 17.0.4)
[info] loading global plugins from /../.sbt/1.0/plugins
...
[info] Publishing build scan...
[info] https://develocity.mycompany.com/s/5563ccpas77ua

Controlling when Build Scans are published

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.

Publishing every build run

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.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withPublishing(Publishing.onlyIf(_ => true))
    )
}

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

Publishing on demand

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 publish configuration:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withPublishing(Publishing.onlyIf(_ => false))
    )
}

When publishing on-demand, you can pass the scan system property to control publishing:

$ sbt -Dscan

This system property overrides the configured value, so it can also be used to disable publishing, regardless of the build setting by setting it to false.

Publishing based on criteria

Many of you will want a bit more control over exactly when Build Scans are published without resorting to using -Dscan each time. You may want to publish Build Scans only under the following conditions:

  1. When the build fails

  2. When the user running the build is authenticated with Develocity

  3. If the build is running on CI

Such scenarios are covered by configuring a custom predicate.

Limit publishing of Build Scans on failure
ThisBuild / develocityConfiguration ~= { previous =>
  val onlyOnFailure = Publishing.onlyIf { ctx => ctx.buildResult.failures.nonEmpty }
  previous
    .withBuildScan(
      previous.buildScan
        .withPublishing(onlyOnFailure)
    )
}
Limit publishing of Build Scans to authenticated users
ThisBuild / develocityConfiguration ~= { previous =>
  val onlyIfAuthenticated = Publishing.onlyIf { ctx => ctx.authenticated }
  previous
    .withBuildScan(
      previous.buildScan
        .withPublishing(onlyIfAuthenticated)
    )
}
Restricting Build Scans to CI builds
ThisBuild / develocityConfiguration ~= { previous =>
  val onlyOnCi = Publishing.onlyIf { _ => sys.env.contains("CI") }
  previous
    .withBuildScan(
      previous.buildScan
        .withPublishing(onlyOnCi)
    )
}

Configuring background uploading

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.

Disabling programmatically

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withBackgroundUpload(false)
    )
}

It may be desirable to conditionally set the value based on the environment.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withBackgroundUpload(!sys.env.get("CI").exists(_.toBoolean))
    )
}

Disabling via system property

Background uploading can be disabled by setting the develocity.scan.uploadInBackground system property to false. The system property setting always takes precedence over the programmatic setting.

$ sbt -Ddevelocity.scan.uploadInBackground=false compile test publish

Configuring project identifier

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

Versions before 0.10 of this plugin do not allow specifying project identifier

Configuring programmatically

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withProjectId(ProjectId("myProject"))
}

Configuring via system property

Project identifier can be specified by setting the develocity.projectId. The system property setting always takes precedence over the programmatic setting.

$ sbt -Ddevelocity.projectId=myProject compile test publish

Capturing build output

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

When to disable

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.

How to disable

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

Programmatically

To disable programmatically, set the buildLogging option to false:

Disabling build output capturing
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withCapture(
          previous.buildScan.capture
            .withBuildLogging(false)
        )
    )
}
Via system property

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 -Ddevelocity.scan.captureBuildLogging=false compile test publish

Capturing resource usage

(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.

The minimum sbt version required to capture usage insights is 1.7.0. When using the Develocity sbt plugin 1.1+ with earlier versions of sbt, resource usage capturing will be automatically disabled, and a warning message will be printed.

When to disable

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.

How to disable

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

Programmatically

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

Disabling resource usage capturing
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withCapture(
          previous.buildScan.capture
            .withResourceUsage(false)
        )
    )
}
Via system property

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.

$ sbt -Ddevelocity.scan.captureResourceUsage=false compile test publish

Extending Build Scans

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:

scan with custom data 1
Figure 1. A Build Scan containing tags and links
scan with custom data 2
Figure 2. A Build Scan containing custom values

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":

build scan filtered list
Figure 3. A filtered list of Build Scans in Develocity

Adding tags

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.

They can be added at build time via the buildScan.withTags (to replace all tags) or buildScan.tag (to add a single tag) utility methods:

Adding tags to a build’s Build Scans
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .tag(if (sys.env.contains("CI")) "CI" else "Local")
        .tag(sys.props("os.name"))
    )
}
Add the scan.tag.<tag> system property to sbt
$ sbt -Dscan.tag.CI -Dscan.tag.$(uname -o)

As demonstrated by the example above, tags are typically applied either as fixed strings within a condition or evaluated at runtime from the environment. But there are no set rules that you need to follow—these are only suggestions.

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.

There are limits on captured tags:

  • maximum tag count: 50

  • maximum tag length: 200 characters

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.

They can be added at build time via the buildScan.withLinks (to replace all links) or buildScan.link (to add a single link) utility methods:

Adding a VCS URL to a build’s Build Scans
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .link("VCS", url(s"https://github.com/myorg/sample/tree/${sys.props("vcs.branch")}"))
    )
}
Adding a link via the command line
$ sbt -Dscan.link.VCS=https://github.com/myorg/my-super-project/tree/my-new-feature

The above example demonstrates how you can attach a link to an online VCS repository that points to a specific branch provided as a system property.

Links are Scala pairs, with the first field being the label, and the second one a valid URL. The <label> 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 1, which shows how a label Source becomes a hyperlink that anyone viewing the Build Scan can follow.

There are limits on captured links:

  • maximum link count: 20

  • maximum link label length: 100 characters

  • maximum link url length: 100,000 characters

Adding custom values

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.

Adding custom values to a build’s Build Scans
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .value("Scala version", scalaVersion.value)
    )
}
Adding custom values via the command line
$ sbt "-Dscan.value.Git branch=$(git branch --show-current)"

This examples shows that you can include any sbt setting value. This applies to tags and links as well.

As with tags, you can filter Build Scans by custom values in Develocity.

There are limits on captured custom values:

  • maximum custom value count: 1,000

  • maximum custom value key length: 1,000 characters

  • maximum custom value value length: 100,000 characters

Capturing settings and configuration options

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.

Background Build Scan publication

Indicates whether the build was configured to upload the Build Scan in the background.

Information about how to configure background uploading for Build Scans can be found in Configuring background uploading section.

Build output capturing

Indicates whether the console log messages generated during the build are captured and displayed in Build Scans.

Information about how to configure build output capturing for Build Scans can be found in Capturing build output section.

Use Coursier

Indicates whether the build was configured to use Coursier for dependencies resolution.

Coursier is the default dependency resolution library since sbt 1.3.0

Offline

Indicates whether the sbt was configured to work without a network connection where possible.

Turbo

Indicates whether the build was configured to use optional performance optimization features.

Turbo mode is available since sbt 1.3.0.

Parallel execution

Indicates whether the build was configured to use parallel tasks execution.

Information about parallel tasks execution can be found in the reference documentation.

SemanticDB Scalac plugin

Indicates whether the projects in the build were configured to use SemanticDB Scalac plugin.

SemanticDB support is available since sbt 1.3.0.

Interactive mode

Indicates whether the build was run from within the sbt shell, or in batch mode.

Information about the sbt interactive mode can be found in the reference documentation.

Obfuscating identifying data

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:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withObfuscation(
          previous.buildScan.obfuscation
            .withUsername(_.reverse)
        )
    )
}

Obfuscating the hostnames:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withObfuscation(
          previous.buildScan.obfuscation
            .withHostname(_.toCharArray.map(_.getNumericValue).mkString("-"))
        )
    )
}

Obfuscating the IP addresses:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withObfuscation(
          previous.buildScan.obfuscation
            .withIpAddresses(_.map(_ => "0.0.0.0"))
        )
    )
}

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

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withObfuscation(
          previous.buildScan.obfuscation
            .withExternalProcessName(_ => "non-build-process")
        )
    )
}

Capturing test data in a custom configuration

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:

build.sbt
// The configuration for which you wish to capture test data
lazy val MyCustomConfig = config("Custom").extend(Test)

lazy val myProject = project(...).settings(
  // Add the Develocity test settings in your custom configuration:
  inConfig(MyCustomConfig)(DevelocityPlugin.testSettings)
)

Using the Build Cache

(sbt plugin 1.1+)

The Build Cache speeds up your builds by reusing outputs from any previous build, on any machine that is connected to the same Build Cache backend. It does this by reducing the inputs of a task execution down to a strong hash key and storing the execution’s output under that key. It supports a local Build Cache that allows other subsequent builds on the same machine to reuse the outputs whenever they execute a task with the same inputs. The full benefit of the Build Cache is realized when also using the remote backend that Develocity provides. This remote Build Cache allows you to share cached outputs across your whole team, including local and CI builds.

Please refer to the Build Cache guide for step-by-step instructions on how to get started and in-depth explanations of important concepts. Moreover, the guide shows how to measure the effectiveness of the Build Cache in your project and explains how to roll out the Build Cache in your organization.

The build caching functionality for sbt requires a Develocity license. The free scans.gradle.com server does not allow using the Build Cache.

Configuring the Build Cache

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

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://develocity.mycompany.com"))
    )
}

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:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withServer(
      previous.server
        .withUrl(url("https://develocity.mycompany.com"))
        .withAllowUntrusted(true)
    )
}

Configuring the local Build Cache

The plugin uses a local Build Cache to store build outputs in the local filesystem. It prevents network round-trips by storing both outputs that local builds created and outputs that were downloaded from the remote Build Cache.

Disabling the local Build Cache

The local Build Cache is enabled by default. The local Build Cache can be disabled by providing a LocalBuildCache where the enabled field is set to false:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withLocal(
          previous.buildCache.local
            .withEnabled(false)
        )
    )
}
Disabling local store

By default, outputs of a given task are stored in the local Build Cache if it is enabled and the scope of the task is clean. Storing outputs in the local Build Cache can be disabled explicitly by setting the storeEnabled option to false.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withLocal(
          previous.buildCache.local
            .withStoreEnabled(false)
        )
    )
}
Changing the local Build Cache directory

The local Build Cache is located at ${user.home}/.sbt/1.0/.develocity/build-cache by default. This can be changed by setting the directory option.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withLocal(
          previous.buildCache.local
            .withDirectory(file("path/to/local/build-cache"))
        )
    )
}

It is a common practice in large organizations to put the user home on a network share. Since the underlying motivation of a local Build Cache is to prevent network round-trips, you should explicitly configure the local Build Cache directory to a path on the local filesystem.

Configuring local Build Cache cleanup

To prevent the local Build Cache from growing in size indefinitely, the local Build Cache directory is cleaned up periodically. By default, the cleanup interval is 24 hours and the retention time is 7 days. The cleanup can be disabled by setting the enabled option to false.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withLocal(
          previous.buildCache.local
            .withCleanup(
              previous.buildCache.local.cleanup
                .withEnabled(false)
            )
        )
    )
}

The cleanup interval and retention time are controlled by the interval and retention options. The formats accepted are based on the ISO-8601 duration format PnDTnHnMn.nS.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withLocal(
          previous.buildCache.local
            .withCleanup(
              previous.buildCache.local.cleanup
                .withRetention(java.time.Duration.ofDays(30))
                .withInterval(java.time.Duration.ofDays(10))
            )
        )
    )
}

Configuring the remote Build Cache

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

Using a different Build Cache node

The address of the remote Build Cache node can be configured in the server option.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withRemote(
          previous.buildCache.remote
            .withServer(
              previous.buildCache.remote.server
                .withUrl(url("http://my-node/cache/"))
            )
        )
    )
}

Note that you still need to configure the address of your Develocity server in the top-level server option.

Similar to the top-level Develocity server configuration, the remote Build Cache server configuration also provides an allowUntrusted option to circumvent certificate warnings:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withRemote(
          previous.buildCache.remote
            .withServer(
              previous.buildCache.remote.server
                .withUrl(url("https://my-node/cache/"))
                .withAllowUntrusted(true)
            )
        )
    )
}

This is a convenient workaround during the initial evaluation, but it is a serious security issue and should not be used in production.

Supplying remote Build Cache credentials

The same access key credential used for Build Scan publishing is used for build cache access control.

Alternatively, a specific username and password can be specified that will be used instead of any available access key. The username and password can be specified directly in your Develocity configuration.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withRemote(
          previous.buildCache.remote
            .withServer(
              previous.buildCache.remote.server
                .withUsernameAndPassword("my-username", "my-password")
            )
        )
    )
}

Instead of putting plain-text passwords into the configuration file, you should inject them via environment variables as demonstrated below.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  val buildCacheCredentials = for {
    username <- sys.env.get("DEVELOCITY_CACHE_USERNAME")
    password <- sys.env.get("DEVELOCITY_CACHE_PASSWORD")
  } yield UsernameAndPassword(username, password)

  previous
    .withBuildCache(
      previous.buildCache
        .withRemote(
          previous.buildCache.remote
            .withServer(
              previous.buildCache.remote.server
                .withUsernameAndPassword(buildCacheCredentials)
            )
        )
    )
}
Disabling the remote Build Cache

The remote Build Cache is enabled by default. This can be changed by setting the enabled option to false.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withRemote(
          previous.buildCache.remote
            .withEnabled(false)
        )
    )
}
Enabling remote store

Since the remote Build Cache is shared with other developers and CI machines, storing in the remote Build Cache is disabled by default. Storing outputs in the remote Build Cache can be enabled by setting the storeEnabled option to true.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withRemote(
          previous.buildCache.remote
            .withStoreEnabled(false)
        )
    )
}

In general, the remote Build Cache should only be populated by controlled build environments such as CI servers. Therefore, the recommendation is to only enable it on the CI server.

Using Expect-Continue

The HTTP Build Cache client allows opt-in use of HTTP Expect-Continue. This causes PUT requests to happen in two parts: first a check whether a body would be accepted, then transmission of the body if the server indicates it will accept it. This is particularly suitable for Build Cache servers that routinely redirect or reject PUT requests, as it avoids transmitting the cache entry just to have it rejected (e.g. the cache entry is larger than the Build Cache will allow). This additional check incurs extra latency when the server accepts the request, but reduces latency when the request is rejected or redirected.

While the Develocity Build Cache Node supports Expect-Continue, not all HTTP servers and proxies reliably do. Be sure to check that your Build Cache server does support it before enabling.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withRemote(
          previous.buildCache.remote
            .withServer(
              previous.buildCache.remote.server
                .withUseExpectContinue(true)
            )
        )
    )
}
Redirects

3xx redirecting responses will be followed automatically.

Servers must take care when redirecting PUT requests as only 307 and 308 redirect responses will be followed with a PUT request. All other redirect responses will be followed with a GET request, as per RFC 7231, without the entry payload as the body.

Allowing insecure protocols

Using the remote Build Cache by default enforces the use of HTTPS to make sure your data is only sent via encrypted connections. If the Build Cache server, or any server in a redirect chain, does not use HTTPS the request will be aborted. This validation can be disabled by setting the allowInsecureProtocol option to true.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withRemote(
          previous.buildCache.remote
            .withServer(
              previous.buildCache.remote.server
                .withAllowInsecureProtocol(true)
            )
        )
    )
}

This is a convenient workaround during the initial evaluation, but it is a serious security issue and should not be used in production.

Troubleshooting

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.

Debugging cache operations

Logging of the Build Cache related operations in the sbt plugin can be increased to make analyzing problems with Build Caching easier. To enable verbose logging of the Build Cache, set the system property develocity.internal.cache.verbose. By default, these additional log messages are logged at the DEBUG level. To set a different level, such as INFO for instance, set the system property develocity.internal.cache.defaultLogLevel to the desired log level.

$ sbt -Ddevelocity.internal.cache.verbose=true -Ddevelocity.internal.cache.defaultLogLevel=info "proj / test"
(...)
[info] Computing cache key 'proj / Test / test / develocityTaskCacheKey' (8 components):
[info] Hashing 'proj / Test / develocityFilteredTests' produced '585e21fb889d22eb339ba04f7b41bd66'
[info] Hashing '. / loadedTestFrameworks' produced '4947226c97108a368683000852bf4f2f'
[info] Hashing 'proj / Test / test / testExecution' produced '6c4c2b176720e67d3aa1c5a74af016bd'
[info] Hashing 'proj / Test / develocityFullClasspath / outputFileStamps' produced '8e20e5baf456d5605a42e5d5fc404806'
[info] Hashing '. / testForkedParallel' produced 'b55cff6ee5ab10468335f878aa2d6251'
[info] Hashing 'Global / javaOptions' produced 'bc764cd8ddf7a0cff126f51c16239658'
[info] Hashing '. / classLoaderLayeringStrategy' produced '1f6ccf510fa0af8381f1791b6198e06d'
[info] Hashing '. / name' produced '641a7d11054d49795fac52da80768b9e'
[info] Computed cache key 'proj / Test / test / develocityTaskCacheKey': 'b3bdb1976a81fb040f5f2d94fd9a25b8'
(...)

Finding the cause of cache misses

Sometimes you might encounter a situation where a task execution is not avoided by using the Build 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 tasks 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, compare the output of sbt with verbose Build Cache logging enabled, as shown above.

Viewing test results

The Develocity plugin will capture test execution results and publish them to the Develocity server. After your Build Scan® is ready, you can view and analyze the results.

Any test framework that is compatible with sbt’s test interface should work with Develocity without requiring any change. Contact us at support.gradle.com if the results are not correctly displayed for the test framework that you are using.

The Test overview page

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.

test overview

Test outcomes

Every task, test suite and test case has an outcome. For a task, the outcome is either SUCCESS, indicating that the task was successful, FLAKY, which means that at least one test suite was flaky, or FAILED, if a test suite has failed.

For test suites, the outcome can be SUCCESS, meaning that all executed test cases were successful, FAILED, indicating that at least one test case failed, FLAKY, meaning that at least one test case was successful only after retry, or SKIPPED, meaning that the test suite was not executed.

For test cases, the outcome can be SKIPPED, meaning that the test case was not executed, SUCCESS, meaning that the test case was successful, FAILED indicating that the test case was failed, or FLAKY, meaning that the test case was successful only after retry.

Test timings

On a task, the total time corresponds to the total amount of wall clock time the task took to execute.

On a test suite, the total time corresponds to the total amount of wall clock time the test suite took to execute. The total time is unavailable when tests run in a forked JVM.

On a test case, the total time corresponds to the total amount of wall clock time the test case took to execute. Clicking on a test suite will open the details for this test suite, which will display the results of the test cases which ran as part of this test suite.

Test suite details page

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

test suite details

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.

Test case details page

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

test case details

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.

Known limitations

Missing durations when forking

Because of how sbt reports test events in case a test suite runs in a forked JVM, it is not possible to accurately report a test suite's total, own and serial durations. Because these durations are missing, the parent test task's own and serial durations are not available either when tests are run in a forked JVM.

Missing test case durations

Some test frameworks do not report the duration of a test case duration, and Develocity can therefore not show that information on the test results pages. The following test frameworks are known not to report test case durations:

When a test case duration is not reported, the following durations will also not be available in Develocity (because they can’t be computed correctly):

  • The test case total duration

  • Its parent test suite own and serial duration

  • Its parent task serial time

Using Test Retry

When test retry is enabled, any failed tests are retried after all the tests have been executed. The process repeats with tests that continue to fail until the maximum specified number of retries has been attempted, or there are no more failing tests.

By default, the test task does not fail when all failed tests pass after a retry. This setting can be changed so that tests that pass on retry cause the task to fail.

Tests that initially fail but pass on retry are considered “flaky” by Develocity. For information on how to detect flaky tests with test retry, please consult the Develocity Flaky Test Detection Guide.

Configuration

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.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withTestRetry(
      previous.testRetry
        .withFlakyTestPolicy(FlakyTestPolicy.DoNotFail) (1)
        .withMaxRetries(0) (2)
        .withMaxFailures(0) (3)
        .withClassesFilter((name: String, annotations: List[String]) => true) (4)
        .withClassRetryFilter((name: String, annotations: List[String]) => false) (5)
    )
}
1 Whether the build should fail if there are failing tests, even if they eventually pass. Use FlakyTestPolicy.Fail to fail the build if flaky tests are detected.
2 The maximum number of times to retry an individual test. Test retry is disabled unless this value is greater than zero.
3 The maximum number of test failures allowed before retrying is disabled for the current test run. This setting defaults to 0, which results in no limit.
4 A filtering function to determine which test classes are eligible for retry. By default, all classes are eligible.
5 A filtering function to determine which test classes should be entirely retried, instead of only their failing test cases. By default, no classes are entirely retried.

Retrying only some tests

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.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withTestRetry(
      previous.testRetry
        .withMaxRetries(3)
        .withClassesFilter { (name, annotations) =>
          // name is a fully qualified class name
          // annotations is the list of fully qualified annotation class names
          name == "com.example.MyKnownFlakyTest" || annotations.contains("com.example.Retryable")
        }
    )
}

Retrying on class-level

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.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withTestRetry(
      previous.testRetry
        .withMaxRetries(3)
        .withClassRetryFilter { (name, annotations) =>
          // name is a fully qualified class name
          // annotations is the list of fully qualified annotation class names
          name.endsWith("IntegrationTest") || annotations.contains("com.example.RetryClass")
        }
    )
}

Retrying only for CI builds

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.

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withTestRetry(
      previous.testRetry
        .withMaxRetries(if (sys.env.contains("CI")) 3 else 0) (1)
        .withMaxFailures(20)
        .withFlakyTestPolicy(FlakyTestPolicy.DoNotFail)
    )
}
1 Enable retrying tests only when running in CI

Compatibility Matrix

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.

Test framework

Retry entire test class

Retry only failed test cases

ScalaTest

Supported in all versions

Supported in all versions

JUnit

Supported in all versions

Requires junit-interface v0.13.3 or later

MUnit

Supported in all versions

Requires MUnit v1.0.0-M3 or later

ScalaCheck

Supported in all versions

Requires this patch

Specs2

Supported in all versions

Requires Specs2 v4.20.5 or later or v5.5.1 or later

ZIOTest

Supported in all versions

Requires ZIO v2.1.0 or later

µTest

Supported in all versions

Requires this patch

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

Troubleshooting

Failed background Build Scan uploads

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.

Slow resolution of host name

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:

/etc/hosts
127.0.0.1   localhost mbpro.local
::1         localhost mbpro.local

Appendix A: API reference

Please see the API reference for more details about programmatic configuration of the Develocity sbt plugin.

Appendix B: Settings and tasks provided by the Develocity sbt plugin

The following settings and tasks are exposed by the Develocity sbt plugin.

Tasks

develocityBuildScanPublishPrevious

Publishes the Build Scan captured by the last build.

develocityProvisionAccessKey

Authenticates your build environment with Develocity.

Appendix C: Captured information

The Develocity sbt plugin captures information while the build is running and transmits it to a server after the build has completed.

Most of the information captured can be considered to be build data. This includes the name of the projects in your build, the tasks, plugins and other things of this nature. Some more general environmental information is also captured. This includes your Java version, operating system, hardware, country, timezone and other things of this nature.

Notably, the actual source code being built and the output artifacts are not captured. However, error messages emitted by compilers or errors in tests may reveal aspects of the source code.

Listing

The list below details the notable information captured by the Develocity sbt plugin and transmitted in a Build Scan.

  • Environment

    • Username (system property 'user.name') (Can be obfuscated)

    • Local hostname (environment variable 'COMPUTERNAME' / 'HOSTNAME') (Can be obfuscated)

    • Public hostname (Can be obfuscated)

    • Local IP addresses (Can be obfuscated)

    • Build Java Virtual Machine

    • Operating System

    • Hardware

  • Build

    • Build invocation options (e.g. requested commands, switches)

    • Build console output

    • Build failure exception messages and stacktraces

    • Executed tasks

    • Executed tests

    • Background Build Scan publication

Access

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.

Appendix D: Additional Build Cache details

Cacheable tasks

The plugin caches the following tasks out of the box:

  • Compile / compileIncremental

  • Test / compileIncremental

  • Test / executeTests

  • Test / testOnly

  • Test / testQuick

  • IntegrationTest / compileIncremental

  • IntegrationTest / executeTests

  • IntegrationTest / testOnly

  • IntegrationTest / testQuick

Enabling Build Cache in a custom sbt.Configuration

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:

build.sbt
val Custom = config("Custom")
val myProject = project.in(file("myProject"))
  .settings(
    // Your usual settings
    // Add this for each Configuration you want to enable Build Cache for:
    DevelocityPlugin.develocitySettings(Custom)
  )

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:

build.sbt
DevelocityPlugin.develocitySettings(Custom, forceTestSettings = true)

Understanding requireClean = true

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:

builds.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildCache(
      previous.buildCache
        .withRequireClean(false)
    )
}

What is a clean build?

In sbt, cleaning is done by executing the clean task. Like any other task, it is executed in a given scope. After the clean task has run in a scope S, Develocity will consider that this scope S is clean, and will allow tasks running in this scope to push to the Build Cache.

In batch mode, if a scope has been cleaned, it remains clean for the entire sbt execution. In interactive mode, a clean scope will remain clean until the next task engine run which executes no clean task finishes.

Caching the compile task

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 Scala compiler version

  • The project name

  • The input sources

  • The external dependency classpath

  • The incremental compiler options

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

sbt> show proj / Compile / compile / develocityTaskCacheKey
[info] 3f2c516d91677bbe810b373da00357b0

Caching the test, testOnly and testQuick tasks

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 project name

  • The filtered tests classes

  • The test frameworks

  • The test execution configuration

  • The classpath

  • If applicable, the parsed user input (for testOnly and testQuick)

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

sbt> show proj / Test / test / develocityTaskCacheKey
[info] 0d02cc0759ec8fe81cb436e6f7e526b8

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

sbt> show proj / Test / testOnly / develocityInputTaskCacheKey com.example.MyTest
[info] 524f957a300cd3334b7ae633b9a5dd3b

Appendix E: Release history

1.1.1

26th August 2024
  • [NEW] Build Scan: Use a custom user agent for HTTP requests

  • [FIX] Build Scan: Display name extraction for Java commands with multiple -jar arguments fails when resource usage capturing is enabled

  • [FIX] Build Scan: Output is redirected to the wrong stream in specific configurations

  • [FIX] Build Cache: sjsir files are missing from the build cache

  • [FIX] Build Cache: nir files are missing from the build cache

  • [FIX] Build Cache: A race condition could cause resources to be deleted from the META-INF folder while compilation outputs are restored from the cache

Compatible with scans.gradle.com and Develocity 2024.2 or later.

1.1

19th August 2024
  • [NEW] Build Scan: Resource usage observability in Build Scan

  • [NEW] Introducing Local and Remote Build Cache support for sbt

  • [NEW] Rename system properties to use develocity. prefix

  • [FIX] High memory usage in specific scenarios

  • [FIX] Unexpected build failure may occur while reloading

Compatible with scans.gradle.com and Develocity 2024.2 or later.

1.0.1

12th April 2024
  • [FIX] IntelliJ build import hangs when publishing Build Scans to scans.gradle.com

Compatible with scans.gradle.com and Develocity 2024.1 or later.

1.0

19th March 2024
  • [NEW] Build Scan: Test retry and flaky test detection

  • [NEW] Interactive prompt to accept the Terms Of Use

  • [NEW] Build Scan: Capture default charset of the build JVM

  • [NEW] Build Scan: Allow opt-out from console logs capturing

  • [NEW] Build Scan: Improve the capture of console logs from Coursier

  • [NEW] Build Scan: Capture executed tasks

  • [NEW] Build Scan: Improved task progress listener with sbt version 1.10.0+

  • [NEW] Build Scan: Capture executed tests

  • [NEW] Build Scan: Do not publish Build Scans for state manipulation commands

  • [FIX] Develocity sbt plugin throws errors when executing remote builds

  • [FIX] Build Scan: Cancelling a command also cancels the Build Scan

  • [FIX] Build Scan: Builds using the resumeFromFailure and onFailure commands report incorrect build result

Compatible with scans.gradle.com and Develocity 2024.1 or later.

0.10.1

12th October 2023
  • [NEW] Added capture of sbt command success/error log events

  • [FIX] Use interactive mode with IntelliJ’s sbt shell

  • [FIX] Create default storage directory in correct sbt home

Compatible with scans.gradle.com and Develocity 2023.3 or later.

0.10

13th September 2023
  • [NEW] Add support for project level access control

  • [NEW] Add capturing of logs written to standard output and standard error

Compatible with scans.gradle.com and Develocity 2023.3 or later.

0.9

19th July 2023
  • [NEW] Initial beta release compatible with Develocity 2023.2

Compatible with scans.gradle.com and Develocity 2023.2 or later.

Appendix F: Compatibility with sbt and Develocity

Compatibility between versions of sbt, Develocity, and the Develocity sbt plugin can be found here.

Appendix G: Verifying the signature of the plugin jar

The plugin jar is published to Maven Central alongside its signature (cf. OSSRH Guide). The public key is published to https://keys.openpgp.org. You can verify the signature as follows:

$ curl -OL https://repo1.maven.org/maven2/com/gradle/sbt-develocity_2.12_1.0/1.1.1/sbt-develocity-1.1.1.jar && \
  curl -OL https://repo1.maven.org/maven2/com/gradle/sbt-develocity_2.12_1.0/1.1.1/sbt-develocity-1.1.1.jar.asc && \
  gpg --keyserver keys.openpgp.org --recv-key  7B79ADD11F8A779FE90FD3D0893A028475557671 && \
  gpg --verify sbt-develocity-1.1.1.jar.asc sbt-develocity-1.1.1.jar

The output of the last command should look similar to the following:

gpg: Signature made Thu Oct 12 12:27:12 2023 CEST
gpg:                using RSA key 893A028475557671
gpg: Good signature from "Gradle Inc. <info@gradle.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7B79 ADD1 1F8A 779F E90F  D3D0 893A 0284 7555 7671

This verifies that the artifact was signed with the private key that corresponds to the imported public key. The warning is emitted because you haven’t explicitly trusted the imported key (hence [unknown]). One way of establishing trust is to verify the fingerprint over a secure channel. Please contact technical support should you wish to do so.

The access key used to sign older versions of Develocity sbt Plugin is revoked. Verifying the signature of these prior versions is no longer possible.

Appendix H: Known issues

Build Scan

Build cancellation

On Linux and macOS, no Build Scan is published when a build is canceled. This is intentional, as incomplete Build Scans could cause errors or misleading information within Develocity. On Windows, however, a Build Scan is published even after cancellation. Be aware that these scans might contain errors or unexpected data when viewed in Develocity; it’s recommended that you remove them manually.

Console log

Log messages via sLog

The Develocity sbt plugin does not capture logs generated via the sbt sLog logger (refer to the sbt documentation log messages in a setting for details).

If sLog is used inside a task definition, use streams.value.log.info instead (as suggested by the related sbt documentation) for the log messages to be captured in Build Scans.

If sLog is used inside a setting definition, no workaround is available.

Failure

javax.management.InstanceAlreadyExistsException when Log4J is used

If log4j usage for internal loggers is enabled via the setting ThisBuild / useLog4J := true, an unexpected javax.management.InstanceAlreadyExistsException may be thrown. This is a known issue that can be ignored.

Failures happening outside the task engine are not reported

(sbt version <1.10.0)

If a failure occurs outside of task evaluation (i.e. purely in an sbt command), then the failure will not be registered by Develocity, and the build will not be marked as failed in Develocity.

build.sbt
commands += Command.command("fail") { _ => ??? } // No failure reported when calling `fail` in sbt < 1.10.0

The workaround is to update to sbt 1.10.0 or later.

Appendix I: Deprecations

System properties

(sbt plugin 1.1+)

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

  • gradle.scan.uploadInBackground was renamed to develocity.scan.uploadInBackground

  • gradle.scan.captureBuildLogging was renamed to develocity.scan.captureBuildLogging

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.

Configuration

(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:

build.sbt
ThisBuild / develocityConfiguration ~= { previous =>
  previous
    .withBuildScan(
      previous.buildScan
        .withBackgroundUpload(false)
    )
}

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.