Gradle Enterprise sbt Plugin User Manual

Gradle Enterprise 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 scans

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

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:

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.

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.

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:

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

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.

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 code snippets.

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

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

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

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

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.tags field:

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.

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.links field:

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.

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.

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 Gradle Enterprise.

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.

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

Coursier is the default dependency resolution library since sbt 1.3.0

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

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

Turbo mode is available since sbt 1.3.0.

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

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

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

SemanticDB support is available since sbt 1.3.0.

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.

(sbt plugin 0.9+)

Setting storing the Gradle Enterprise configuration.

(sbt plugin 0.9+)

Publishes the build scan captured by the last build.

(sbt plugin 0.9+)

Authenticates your build environment with Gradle Enterprise.

(sbt plugin 0.9+)

The default storage directory (.gradle-enterprise) is always located inside the default sbt global directory (${user.home}/.sbt), even if a different sbt global directory is set via the sbt BuildPaths.globalBaseDirectory attribute or the sbt.global.base system property.

The storage directory can be changed either via the gradle.enterprise.storage.directory system property or by specifying the desired location via the configuration class in the sbt build file.

(sbt plugin 0.9)

Logs of the artifacts downloaded by Coursier are not captured in build scans. This is because they are printed to the standard output, which does not get captured in build scans (a known limitation, see Standard output).

To capture Coursier logs use the Gradle Enterprise sbt plugin 0.10 or later.

(sbt plugin 0.9+)

The Gradle Enterprise 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.

(sbt plugin 0.9)

The Gradle Enterprise sbt plugin 0.9 does not capture logs generated by the MUnit testing library because they are printed to the standard output (a known limitation, see Standard output).

To capture logs generated by MUnit in build scans use the Gradle Enterprise sbt plugin 0.10 or later. Alternatively add the following to your projects' settings:

(sbt plugin 0.9)

The Gradle Enterprise sbt plugin 0.9 does not capture messages printed to the standard output.

To capture messages printed to the standard output use the Gradle Enterprise sbt plugin 0.10 or later. Alternatively use streams.value.log.info inside a task definition for the log messages to be captured in build scans. Refer to the sbt documentation log messages in a task for details.

(sbt plugin 0.9+)

If an executing task throws a java.lang.OutOfMemoryError (or any other subclass of java.lang.VirtualMachineError), the build scans will not report the failure nor capture the error reported in the log.

(sbt plugin 0.9)

The built-in sbt shell is not supported. The workaround is to update to version 0.10+ of the plugin or launch sbt from the terminal.

(sbt plugin 0.9+)

In interactive mode, when executing tasks from a specific subproject rather than the root project, the requested task will be wrongly identified as the last command issued to switch project (i.e. project <projectname>), rather than the actual task executed after having switched project.

The workaround is to execute all commands from the root project using the <projectname>/<task> notation instead.