The Gradle Enterprise Gradle plugin enables integration with Gradle Enterprise and scans.gradle.com.

This plugin was previously named and referred to as the “build scan” plugin. With the release of Gradle 6.0 and version 3.0 of this plugin, it has been renamed to the “Gradle Enterprise” plugin. As such, when discussing older versions this document uses the term “build scan” when referring to the plugin.

Getting set up

Version 3.0 is the latest version and is compatible with all Gradle 5.x and later versions. See Gradle 4.x and earlier if you are using an earlier version of Gradle.

The instructions in this section describe applying and configuring the plugin for a single Gradle project. See Integrating many projects for help with integrating all projects built within an environment.

Applying the plugin

Gradle 6.x and later

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

settings.gradle
plugins {
  id "com.gradle.enterprise" version "3.0"
}
settings.gradle.kts
plugins {
  id("com.gradle.enterprise").version("3.0")
}

The plugin adds a gradleEnterprise {} extension to the settings script for configuring the plugin, and adds a buildScan {} extension extension to the root project. Either can be used to configure the plugin.

For the remainder of this documentation, configuration examples use the buildScan {} extension in build scripts. In all cases, this configuration can be specified within the settings script by placing the configuration within the gradleEnterprise {} extension configuration.

settings.gradle
plugins {
  id "com.gradle.enterprise" version "3.0"
}

gradleEnterprise {
    buildScan {
        // plugin configuration
    }
}
settings.gradle.kts
plugins {
  id("com.gradle.enterprise").version("3.0")
}

gradleEnterprise {
    buildScan {
        // plugin configuration
    }
}

Gradle 5.x

This version of Gradle uses com.gradle.build-scan as the plugin ID. The plugin must be applied to the root project of the build.

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

The plugin adds a buildScan {} extension extension to the root project for configuring the plugin.

Connecting to Gradle Enterprise

To connect to a Gradle Enterprise instance, you must configure the location of the Gradle Enterprise server.

build.gradle
buildScan {
    server = "https://gradle-enterprise.mycompany.com"
}
build.gradle.kts
buildScan {
    server = "https://gradle-enterprise.mycompany.com"
}

Allowing untrusted SSL communication

If your Gradle Enterprise 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 allowUntrustedServer option to true:

Disabling SSL certificate checks
buildScan {
    allowUntrustedServer = true
}
Disabling SSL certificate checks
buildScan {
    allowUntrustedServer = 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.

Connecting to scans.gradle.com

If the location of a Gradle Enterprise server is not specified, build scans will be published to scans.gradle.com. This requires agreeing the terms of service, which can be found at https://gradle.com/terms-of-service.

You can agree to the terms of service by adding adding the following configuration to your build.

build.gradle
buildScan {
    termsOfServiceUrl = "https://gradle.com/terms-of-service"
    termsOfServiceAgree = "yes"
}
build.gradle.kts
buildScan {
    termsOfServiceUrl = "https://gradle.com/terms-of-service"
    termsOfServiceAgree = "yes"
}

If you do not agree to the terms of service in your build, you will be asked interactively when trying to publish a build scan to scans.gradle.com each time you try to publish.

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

Integrating your CI tool

The Gradle plugin for Jenkins prominently displays links to the build scan for any Gradle builds that produce build scans. This makes viewing the build scan of CI builds much easier.

jenkins

A TeamCity build scan plugin is also available that provides a prominent link to the build scan for executed builds.

teamcity

Controlling when build scans are published

Build scans are not automatically published after applying the plugin. The following describes the options available for controlling when to publish a build scan.

For Gradle Enterprise users, it is recommended that builds be configured to publish a build scan for every build. This allows Gradle Enterprise to provide more insight on your organization’s builds.

Publishing on demand

You can add the --scan argument to any Gradle build to publish a build scan.

$ gradle assemble --scan
If the build does not apply the plugin, Gradle will automatically apply the most recent version available at the time that version of Gradle was released.

You can also publish a build scan for the most recently run build by invoking the buildScanPublishPrevious task added by the plugin.

$ gradle buildScanPublishPrevious

Since the task name is quite long, it’s worth taking advantage of Gradle’s abbreviated command line notation for tasks:

$ gradle bSPP

Publishing every build

In order to publish a build scan for every build, you can use the publishAlways() directive:

Publishing a build scan for every build execution
buildScan {
    publishAlways()
}
Publishing a build scan for every build execution
buildScan {
    publishAlways()
}

Publishing based on criteria

In order to publish a build scan automatically for some builds, you can use the following directives:

Table 1. Options for automatic publishing based on criteria
Option Description

publishAlwaysIf(boolean)

Publish a build scan if the given condition is true, regardless of whether the build succeeds or fails.

publishOnFailure()

Publish a build scan only when the build fails.

publishOnFailureIf(boolean)

Publish a build scan only if the condition is true and the build fails.

For example, if you only want to publish build scans from your CI system, which is identified by having a CI environment variable, you can do the following:

Restricting build scans to CI builds
buildScan {
    publishAlwaysIf(System.getenv("CI"))
}
Restricting build scans to CI builds
buildScan {
    publishAlwaysIf(!System.getenv("CI").isNullOrEmpty())
}

You can use the other options in the same way. If you want to configure several things based on a set of criteria, you can use an if condition instead:

build.gradle
buildScan {
    if (System.getenv("CI")) {
        publishAlways()
        tag "CI"
    }
}
build.gradle.kts
buildScan {
    if (!System.getenv("CI").isNullOrEmpty()) {
        publishAlways()
        tag("CI")
    }
}

Capturing task input files

(build scan plugin v2.1+, Gradle 5.0+)

Build scans capture hashes of task inputs, to enable identifying changes to inputs when comparing builds, among other features. By default, an overall hash value for each task input property is captured. This enables identifying which properties changed for a task (e.g. the source or the classpath for Java compilation), but not which individual files changed. In order to identify file changes, the paths and content hashes of each individual input file must be captured, which can be enabled.

When to enable

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

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

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

How to enable

Task input files capture can be enabled programmatically via the buildScan extension, or via a system property.

Programmatically

To enable programmatically, use the buildScan extension added by the build scan plugin.

build.gradle
buildScan {
    captureTaskInputFiles = true
}
build.gradle.kts
buildScan {
    isCaptureTaskInputFiles = true
}

Via system property

To enable without modifying the build script, supply a scan.capture-task-input-files system property to the build. If this property is set, with any value other than false, including no value, capture will be enabled. If the property is set with false, capture will be disabled, regardless of any programmatic setting. The environmental setting always takes precedence over the programmatic setting.

The system property may be specified when invoking the build:

$ ./gradlew build -Dscan.capture-task-input-files

Or, can be set as part of the environment with the JAVA_OPTS or GRADLE_OPTS environment variables:

$ export GRADLE_OPTS=-Dscan.capture-task-input-files

Or, can be set in the project’s gradle.properties file, or the user’s gradle.properties file (i.e. ~/.gradle/gradle.properties).

systemProp.scan.capture-task-input-files

See the Build Environment chapter of the Gradle User Manual for more information on specifying system properties.

Extending build scans

(build scan plugin v1.1+)

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 figure 2:

scan with custom data
Figure 1. A build scan containing the different types of custom data

Gradle Enterprise 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 "master":

build scan filtered list
Figure 2. A filtered list of build scans in Gradle Enterprise

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 tag() method:

Adding tags to a build’s build scans
buildScan {
    if (System.getenv("CI")) {
        tag "CI"
    } else {
        tag "Local"
    }

    tag System.getProperty("os.name")
}
Adding tags to a build’s build scans
buildScan {
    tag(if (System.getenv("CI").isNullOrEmpty()) "Local" else "CI")
    tag(System.getProperty("os.name"))
}

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.

The syntax for adding a tag is:

tag(<tag>)

where the <tag> is a string.

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.

Build scan plugin v1.9.1+ impose 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 link() method:

Adding a VCS URL to a build’s build scans
buildScan {
    link "VCS", "https://github.com/myorg/sample/tree/${System.getProperty("vcs.branch")}"
}
Adding a VCS URL to a build’s build scans
buildScan {
    link("VCS", "https://github.com/myorg/sample/tree/${System.getProperty("vcs.branch")}")
}

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.

The syntax for adding a link is:

link(<label>, <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 2, which shows how a label Source becomes a hyperlink that anyone viewing the build scan can follow.

Build scan plugin v1.9.1+ impose limits on captured links:

  • maximum link count: 20

  • maximum link label length: 100 characters

  • maximum link url length: 1,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.

They can be added at build time via the value() method:

Adding custom values to a build’s build scans
buildScan {
    value "Build Number", project.buildNumber
}
Adding custom values to a build’s build scans
buildScan {
    value("Build Number", project.buildNumber)
}

The above example demonstrates how you can read the build number from a project property—assuming you have your build set up for this—and attach it to the build scans as a custom value.

The syntax for adding a value is:

value(<key>, <value>)

where both the <key> and the <value> are strings.

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

Build scan plugin v1.9.1+ impose 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

Adding data at the end of the build

(build scan plugin v1.2+)

The examples you have seen so far work well if when the custom data is available at the beginning of the build. But what if you want to attach data that’s only available later? For example, you might want to label a build as "built-from-clean" if the clean task was run. But you don’t know if that’s the case until the task execution graph is ready.

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

Adding a custom disk usage value at the end of the build
buildScan {
    buildFinished {
        value "Disk usage (output dir)", buildDir.directorySize().toString()
    }
}
Adding a custom disk usage value at the end of the build
buildScan {
    buildFinished {
        value("Disk usage (output dir)", buildDir.walkTopDown().map { it.length() }.sum().toString())
    }
}

The buildFinished() action has access to the rest of the build, including the Project instance, so it can extract all sorts of information. It also has access to a BuildResult instance that you can use to determine whether the build failed or not, like so:

Checking build status from buildFinished()
import com.gradle.scan.plugin.BuildResult
...
buildScan {
    buildFinished { BuildResult result ->
        if (result.failure) {
            value "Failed with", result.failure.message
        }
    }
}
Checking build status from buildFinished()
buildScan {
    buildFinished {
        if (this.failure != null) {
            value("Failed with", this.failure.message)
        }
    }
}

The Gradle build tool has a BuildListener interface that also contains a buildFinished() hook. However, you cannot use this to attach custom data because it is triggered too late. You can use hooks like project.afterEvaluate() or the buildStarted() method of BuildListener because they are executed early enough.

Adding expensive data

(build scan plugin v1.15+)

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

Using background() to capture an expensive custom value
buildScan {
    background {
        def commitId = "git rev-parse --verify HEAD".execute().text.trim()
        value "Git Commit ID", commitId
    }
}
Using background() to capture an expensive custom value
import java.io.ByteArrayOutputStream
...
buildScan {
    background {
        val os = ByteArrayOutputStream()
        exec {
            commandLine("git", "rev-parse", "--verify", "HEAD")
            standardOutput = os
        }
        value("Git Commit ID", os.toString())
    }
}

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

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

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

See the buildScan.background() API reference for more information.

Providing custom data via system properties

(build scan plugin v1.3+)

The examples up to this point have shown how your build file or init script can pull information from the environment, via environment variables and system properties. The build scan plugin also allows you to inject any form of custom data through the use of specially named system properties. This can help you keep your build files clean of too much environment-specific information that may not be relevant to most of the users of the build.

These system properties take the following forms, depending on whether you want to inject a link, a tag or a custom value:

-Dscan.tag.<tag>
-Dscan.link.<label>=<URL>
-Dscan.value.<key>=<value>

Here are some concrete examples, which assume that the build has been configured to publish build scans automatically:

$ gradle build -Dscan.tag.CI
$ gradle build -Dscan.link.VCS=https://github.com/myorg/my-super-project/tree/my-new-feature
$ gradle build "-Dscan.value.CI Build Type=QA_Build"

This feature is particularly useful for continuous integration builds as you can typically easily configure your CI tool to specify system properties for a build. It’s even common for CI tools to be able to inject system properties into a build that are interpolated with information from the CI system, such as build number.

$ gradle build "-Dscan.value.buildNumber=$CI_BUILD_NUMBER"

Capturing the build scan ID or address

(build scan plugin v1.9+)

The address of the build scan is included in the output at the end of the build. However, you may wish to record the ID or URL of the build scan in some other way. The build scan plugin allows you to register a callback that will receive this information. The callback is invoked after a build scan has been successfully published.

The example build script snippet below shows this feature being used to maintain a journal of created build scans.

Gradle Enterprise provides the ability to search for build scans created by a certain user and/or from a particular host (along with other search criteria).

Creating a log of published build scans
import com.gradle.scan.plugin.PublishedBuildScan
...
buildScan {
    buildScanPublished { PublishedBuildScan scan ->
        file("scan-journal.log") << "${new Date()} - ${scan.buildScanId} - ${scan.buildScanUri}\n"
    }
}
Creating a log of published build scans
import java.util.Date
...
buildScan {
    buildScanPublished {
        file("scan-journal.log").appendText("${Date()} - ${this.buildScanId} - ${this.buildScanUri}\n")
    }
}

Please see the buildScan.buildScanPublished() method for API details.

Obfuscating identifying data

(build scan plugin v2.4.2+)

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

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

Obfuscating the username
buildScan {
    obfuscation {
        username { name -> name.reverse() }
    }
}
Obfuscating the username
buildScan {
    obfuscation {
        username { name -> name.reverse() }
    }
}
Obfuscating the hostnames
buildScan {
    obfuscation {
        hostname { host -> host.collect { character -> Character.getNumericValue(character as char) }.join("-") }
    }
}
Obfuscating the hostnames
buildScan {
    obfuscation {
        hostname { host -> host.collect { character -> Character.getNumericValue(character as char) }.join("-") }
    }
}
Obfuscating the IP addresses
buildScan {
    obfuscation {
        ipAddresses { addresses -> addresses.collect { address -> "0.0.0.0"} }
    }
}
Obfuscating the IP addresses
buildScan {
    obfuscation {
        ipAddresses { addresses -> addresses.collect { address -> "0.0.0.0"} }
    }
}

Integrating many projects

While it is typical to apply this plugin directly to a project, it is also possible to use Gradle’s init script functionality to apply it to easily apply it to many projects. This is often used to enable integration for all builds within an environment (i.e. CI builds, or a developer’s machine).

Init scripts can be used with Gradle by specifying the path to a script at build time with the -I option:

$ ./gradlew build -I path/to/init.gradle

Or they can be placed within the ~/.gradle/init.d directory to be automatically applied to very build.

Gradle Enterprise

The following init script example enables any Gradle 5.0 or later build to integrate with a Gradle Enterprise server:

gradle-enterprise-init.gradle
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion

initscript {
    def pluginVersion = "3.0"

    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
    }
}

def isTopLevelBuild = gradle.getParent() == null

if (isTopLevelBuild) {
    def gradleVersion = GradleVersion.current().baseVersion
    def atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
    def atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")

    if (atLeastGradle6) {
        settingsEvaluated {
            if (!it.pluginManager.hasPlugin("com.gradle.enterprise")) {
                it.pluginManager.apply(GradleEnterprisePlugin)
            }
            configureExtension(it.extensions["gradleEnterprise"].buildScan)
        }
    } else if (atLeastGradle5) {
        rootProject {
            pluginManager.apply(BuildScanPlugin)
            configureExtension(extensions["buildScan"])
        }
    }
}

void configureExtension(extension) {
    extension.with {
        publishAlways()
        server = "https://gradle-enterprise.company.com"
        // other configuration
    }
}
gradle-enterprise-init.gradle.kts
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion

initscript {
    val pluginVersion = "3.0"

    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
    }
}

val isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
    val gradleVersion = GradleVersion.current().baseVersion
    val atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
    val atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")

    if (atLeastGradle6) {
        settingsEvaluated {
            if (!pluginManager.hasPlugin("com.gradle.enterprise")) {
                pluginManager.apply(GradleEnterprisePlugin::class)
            }
            extensions["gradleEnterprise"].withGroovyBuilder {
                configureExtension(getProperty("buildScan"))
            }
        }
    } else if (atLeastGradle5) {
        rootProject {
            pluginManager.apply(BuildScanPlugin::class)
            configureExtension(extensions["buildScan"])
        }
    }
}

fun configureExtension(extension: Any) {
    extension.withGroovyBuilder {
        "publishAlways"()
        setProperty("server", "https://gradle-enteprise.company.com")
        // other configuration
    }
}

scans.gradle.com

The following init script example enables any Gradle 5.0 or later build to integrate with scans.gradle.com:

scans-init.gradle
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion

initscript {
    def pluginVersion = "3.0"

    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
    }
}

def isTopLevelBuild = gradle.getParent() == null

if (isTopLevelBuild) {
    def gradleVersion = GradleVersion.current().baseVersion
    def atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
    def atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")

    if (atLeastGradle6) {
        settingsEvaluated {
            if (!it.pluginManager.hasPlugin("com.gradle.enterprise")) {
                it.pluginManager.apply(GradleEnterprisePlugin)
            }
            configureExtension(it.extensions["gradleEnterprise"].buildScan)
        }
    } else if (atLeastGradle5) {
        rootProject {
            pluginManager.apply(BuildScanPlugin)
            configureExtension(extensions["buildScan"])
        }
    }
}

void configureExtension(extension) {
    extension.with {
        termsOfServiceUrl = "https://gradle.com/terms-of-service"
        termsOfServiceAgree = "yes"
        // other configuration
    }
}
scans-init.gradle.kts
import com.gradle.enterprise.gradleplugin.GradleEnterprisePlugin
import com.gradle.scan.plugin.BuildScanPlugin
import org.gradle.util.GradleVersion

initscript {
    val pluginVersion = "3.0"

    repositories {
        gradlePluginPortal()
    }
    dependencies {
        classpath("com.gradle:gradle-enterprise-gradle-plugin:${pluginVersion}")
    }
}

val isTopLevelBuild = gradle.getParent() == null
if (isTopLevelBuild) {
    val gradleVersion = GradleVersion.current().baseVersion
    val atLeastGradle5 = gradleVersion >= GradleVersion.version("5.0")
    val atLeastGradle6 = gradleVersion >= GradleVersion.version("6.0")

    if (atLeastGradle6) {
        settingsEvaluated {
            if (!pluginManager.hasPlugin("com.gradle.enterprise")) {
                pluginManager.apply(GradleEnterprisePlugin::class)
            }
            extensions["gradleEnterprise"].withGroovyBuilder {
                configureExtension(getProperty("buildScan"))
            }
        }
    } else if (atLeastGradle5) {
        rootProject {
            pluginManager.apply(BuildScanPlugin::class)
            configureExtension(extensions["buildScan"])
        }
    }
}

fun configureExtension(extension: Any) {
    extension.withGroovyBuilder {
        setProperty("termsOfServiceUrl", "https://gradle.com/terms-of-service")
        setProperty("termsOfServiceAgree", "yes")
        // other configuration
    }
}

Upgrading to Gradle 6

If you were previously using the build scan plugin 2.x with Gradle 5, upgrading to the the 3.x plugin requires more than just updating the version number. The ID of the plugin has changed, and it now must be applied in the build’s settings file.

To upgrade, first locate where the 2.x plugin is being applied and remove it. This is likely to be in the root build.gradle or build.gradle.kts file, and will look similar to the following:

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

Then, add the following to the settings.gradle or settings.gradle.kts file for the build:

settings.gradle
plugins {
    id "com.gradle.enterprise" version "3.0"
}
settings.gradle.kts
plugins {
    id("com.gradle.enterprise").version("3.0")
}

Any buildScan {} configuration can remain where it is, or be moved to the settings file inside a gradleEnterprise {} block. Please see the Gradle 6.x section above for more information.

settings.gradle
gradleEnterprise {
    buildScan {
        server = "https://gradle-enterprise.company.com"
    }
}
settings.gradle.kts
gradleEnterprise {
    buildScan {
        server = "https://gradle-enterprise.company.com"
    }
}

Gradle 4.x and earlier

Gradle 2.1 - 4.10.2

Gradle versions earlier than 5.0 are not compatible with the latest plugin and features. Plugin version 1.16 is the best available version for such builds. The plugin must be applied to the root project of the build, with ID com.gradle.build-scan.

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

Gradle 2.0

Gradle 2.0 does not support the plugins {} syntax that was introduced in Gradle 2.1. As such, the plugin must be applied differently.

build.gradle
buildscript {
  repositories {
      maven { url "https://plugins.gradle.org/m2/" }
  }
  dependencies {
      classpath "com.gradle:build-scan-plugin:1.16"
  }
}
apply plugin: "com.gradle.build-scan"
build.gradle.kts
buildscript {
  repositories {
      maven(url = "https://plugins.gradle.org/m2/")
  }
  dependencies {
      classpath("com.gradle:build-scan-plugin:1.16")
  }
}
apply(plugin = "com.gradle.build-scan")

Troubleshooting

Slow build startup in MacOS Sierra after applying build scan plugin

An issue with resolving localhost affecting MacOS Sierra can cause a 5 second delay after applying the build scan plugin to your build. Until the issue is fixed, there is a workaround that you can apply 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 Javadoc.

Appendix B: Captured information

The build scan 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, dependencies, names and results of tests 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 build scan plugin and transmitted in a build scan.

  • Environment

    • Username (system property "user.name")

    • Local hostname (environment variable "COMPUTERNAME" / "HOSTNAME")

    • Public hostname

    • Local IP addresses

    • Build Java Virtual Machine

    • Operating System

    • Hardware

  • Build

    • Gradle command-line and invocation options (e.g. requested tasks, switches)

    • Build console output

    • Build failure exception messages and stacktraces

    • Build deprecation messages

    • Project names and structure

    • Executed tasks

    • Executed tests (using Gradle’s JVM Test task)

    • Applied plugins

    • Resolved dependencies

    • Network downloads (performed by Gradle)

    • Gradle Daemon operational data (e.g. start time, build count)

    • Build cache configuration

    • Gradle lifecycle callbacks

Access

Build scans published to a Gradle Enterprise installation are viewable by all users that can reach the server. Gradle Enterprise 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 C: Plugin release history

3.0 - 16th October 2019
Renamed to Gradle Enterprise plugin
Compatibility with Gradle 6

2.4.2 - 10th September 2019
Added support for username, hostname and ip-addresses obfuscation

2.4.1 - 20th August 2019
More reliable capture of logging output
Handle overlapping IDs in dependency resolution
More stable end-of-build handling

2.4 - 8th August 2019
Added support for capturing all dependency selection reasons
Added support for capturing dependency variant details
Added support for capturing rich dependency version constraint information
Added support for capturing dependency platform and constraint details

2.3 - 3rd May 2019
Added support for plugin composite builds
Added support for continuous builds
Added support for capturing the details of annotation processors used during Java compilation

2.2.1 - 1st March 2019
More reliable capture of task input files for buildSrc

2.2 - 27th February 2019
Capture collection callback executions
Capture deprecation traces more compactly
General performance improvements in task inputs capturing

2.1 - 7th December 2018
This version is compatible with Java 8 and later
Capture task input files

2.0.2 - 6th November 2018
This version is compatible with Gradle 5.0 and later
Removed deprecated -Dscan and -Dscan=false system property, use --scan and --no-scan, respectively
Avoid memory leak when connecting to HTTPS server with often changing build classpath

2.0.1 - 29th October 2018
This version was released for compatibility with Gradle 5.0-rc-1,
but is not compatible with subsequent Gradle 5.0 releases. Please use version 2.0.2 or later instead.

2.0 - 17th October 2018
This version was released for compatibility with Gradle 5.0-milestone-1,
but is not compatible with subsequent Gradle 5.0 releases. Please use version 2.0.2 or later instead.

1.16 - 21st August 2018
Capture repositories and source repository for a resolved module component
Capture individual lifecycle listeners and attribute to code unit application
Capture Gradle build script compilation details
Capture deprecated usage notifications
Capture source of included build

1.15.2 - 10th August 2018
Fix for Kotlin script build caching

1.15.1 - 5th July 2018
Fix for potential classloader leak when using buildScan.background()

1.15 - 3rd July 2018
Support capturing expensive custom values/tags/links in the background
Task buildScanPublishPrevious is created lazily
Fixed error when using included build as plugin and in main build

1.14 - 12th June 2018
Further performance improvements
Removal of unnecessary implicit continuous build scan suppression
Capture information on lifecycle hook execution

1.13.4 - 18th May 2018
Improved performance of build scan plugin, particularly during configuration time

1.13.3 - 14th May 2018
Fix incompatibility with new continuous build features in Gradle 4.7

1.13.2 - 8th May 2018
Do not show build scan publishing information when --quiet or -q argument is present
Retry likely temporary network errors while publishing a build scan

1.13.1 - 10th Apr 2018
Improve performance of plugin data capture.

1.13 - 28th Mar 2018
Capture console log from beginning of the build.

1.12.1 - 13th Feb 2018
Fix message when terms of service are declined.

1.12 - 12th Feb 2018
Capture build scans for composite builds.
Capture original task execution time.

1.11 - 5th Dec 2017
Capture test execution, dependency resolution, and project structure data from the beginning of the build.
Improve performance of plugin data capture.
Enhance Gradle version compatibility check.

1.10.3 - 23th Nov 2017
Fix incompatibility with Android Plugin for Gradle 3.0.0.

1.10.2 - 7th Nov 2017
Fix incompatibility with development builds of Gradle 4.4.

1.10.1 - 27th Oct 2017
Fix incompatibility with development builds of Gradle 4.4.

1.10 - 17th Oct 2017
Detect when build was run by a single-use daemon.
Capture default charset of the JVM that executed the build.
Capture build path of each project.

1.9.1 - 10th Oct 2017
Prompt user for license agreement acceptance, if needed.
Capture console output and network activity until closer to the end of the build.
Limit the number and length of captured custom tags, custom links, and custom values.

1.9 - 15th Aug 2017
Capture task graph calculation.
Capture more fine-grained project configuration.
Capture build cache interactions including artifact packing and unpacking.

1.8 - 15th June 2017
Capture resolved requested tasks.
Capture build cache configuration when build cache is enabled.
Capture task inputs for each task when build cache is enabled.
Capture origin build invocation id for tasks with up-to-date and from-cache outcome.
Capture reasons why a task was not up-to-date.
Capture GC and peak heap memory statistics.
Capture more network download activities.
Get notified after successful build scan publication via buildScan.buildScanPublished().
Build scan plugin logs at quiet level.

1.7.4 - 29th May 2017
Fix incompatibility with development builds of Gradle 4.0.

1.7.3 - 19th May 2017
Fix incompatibility with development builds of Gradle 4.0.

1.7.2 - 17th May 2017
Fix incompatibility with development builds of Gradle 4.0.

1.7.1 - 3rd May 2017
Fix incompatibility with development builds of Gradle 4.0.

1.7 - 24th April 2017
Fix NPE when specifying buildScan "server" URL without schema or host.
Overlapping output is captured as a non-cacheable reason for a task.

1.6 - 10th February 2017
Capture whether task outputs are cacheable and the reason if they are not.
Capture network download activities.

1.5 - 11st January 2017
Capture whether tasks were skipped due to having no source.
Capture whether tasks are lifecycle tasks (i.e. no actions).
Add "mailto:" link as custom build scan links.

1.4 - 21st December 2016
Performance improvements when executing many tests.

1.3 - 15th November 2016
Capture tags, links and/or values via conventional system properties.
Reduced payload size when publishing large dependency graphs.

1.2 - 12th October 2016
Capture tags, links and/or values at the end of the build via buildScan.buildFinished().

1.1.1 - 20th September 2016
Fixed issues with creating build scans for some projects via Android Studio.

1.1 - 17th September 2016
Capture user-defined tags, links and arbitrary values.
Create a build scan for every build, or every failed build.
Create a build scan for the immediately previous build.
Publishing a build scan is implicitly disabled when build with --offline.
Publish a build scan over an untrusted HTTPS connection, if explicitly configured.
Several fixes for creating build scans when executing a build through an IDE.

1.0 - 23rd June 2016
Initial release.

Appendix D: Plugin compatibility with Gradle Build Tool and Gradle Enterprise

Compatibility between versions of Gradle, Gradle Enterprise, and the build scan plugin can be found here.