Custom Data in Build Scans
Introduction
Build scans are a great way to easily share data about your build, but what if your team wants to add their own data to those build scans? They can! In addition to the extensive information automatically captured in build scans, you can attach your own custom data to provide even deeper insights into your build. This custom data can take the form of tags, links, and arbitrary custom values in a key-value format.
By adding custom data to your build scans you can make it easy to find builds of a certain type, give quick links to the applicable source code commit on GitHub, add helpful CI build information, and much more. Then, when you share the single build scan link with a teammate, they get quick and easy access to a plethora of information about your build, making it easier for them to diagnose build environment issues, fix test failures, and so on.
If build scans are new to you, you can learn about them in our introductory blog post on the topic. You can also find more details in the Build Scans User Manual, explore some example build scans or experiment with this sample build scan project.
Now let’s go through some examples of adding custom data into your build scans (see the user manual for additional examples).
Tags #
Let’s start with the simplest type of custom data: tags. Tags are a way to add simple pieces of metadata to your build scan. You can use tags to add context to your build, such as whether the build was run locally or on a CI server, whether the build had any local changes, the error type of a failing build, etc. Here is an example build scan that tags the build as having:
- run on CI
- come from the master branch
- included local code changes (“dirty”)
For example, to attach a tag showing whether the build ran locally or on a CI server, you can add the following to its build script:
if (System.getenv("CI")) {
buildScan.tag "CI"
} else {
buildScan.tag "LOCAL"
}
The tag is then displayed under the project name when viewing the build scan:
Links #
In addition to tags, you can include links that readers of your build scan might find useful. For example, you could include a convenient link to the project source on GitHub or a link to the CI results of the Gradle build. This example build scan demonstrates what such links look like.
Let’s say your CI tool makes the build results URL available as an environment variable. You could grab that value and add it as a custom link by using the following code in your build script:
if (System.getenv("CI")) {
buildScan.link "CI build", System.getenv("BUILD_URL")
}
You also have the flexibility to add a link to the current revision or commit of the project’s source code. The following example links the build scan to its corresponding commit on GitHub (as long as the Git command line tools are available):
String commitId = 'git rev-parse --verify HEAD'.execute().text.trim()
buildScan.link "Source", "https://github.com/gradle/gradle-build-scan-quickstart/tree/" + commitId
Links are displayed in the top section when viewing the build scan:
Custom values #
Custom values can be used to make any information part of the build scan. In this example build scan, you can see the corresponding CI build date, CI build number and the name of the Git branch as custom values. These values are available when viewing the build scan or when searching for build scans in Gradle Enterprise. Let’s go through a couple of examples showing how you can add custom values to your build scan.
In our first example, we assume your CI tool injects build information into the build via environment variables. You could then use the following code in your build script to attach the build number and date to the build scan:
if (System.getenv("CI")) {
buildScan.value "CI build number", System.getenv("BUILD_NUMBER")
buildScan.value "CI build date", System.getenv("BUILD_DATE")
}
Since we are setting these custom values from inside a Gradle build script, you have the power to do things like run external commands to capture more information about the project status. For example, you could add the current Git branch of the build by running a Git command and setting a custom value with the result:
String branchName = 'git rev-parse --abbrev-ref HEAD'.execute().text.trim()
buildScan.value "Git branch", branchName
The custom values are displayed on the main page when viewing the build scan:
Command line #
To give you greater flexibility in how you pass custom data to your build scan, you can also specify tags, links, and custom values on the command line. For example, you can quickly attach ad-hoc information to your build scan in order to:
- help debug a specific local build failure
- tag an experimental build
- add CI-specific custom data without modifying your build script
You do this by specifying system properties with the appropriate names, as demonstrated by these examples:
$ gradle build -Dscan.tag.EXPERIMENTAL
$ gradle build -Dscan.link.buildUrl=$CI_BUILD_URL
$ gradle build -Dscan.value.buildNumber=$CI_BUILD_NUMBER
The first adds a tag named “EXPERIMENTAL”, the second adds a link titled “buildUrl”, and the third adds a custom value called “buildNumber”.
Searching based on custom data #
When using build scans on-premises with Gradle Enterprise, you can search for build scans based on custom data such as tags and custom values. For example, you can search for all builds that ran on CI against the master branch using the terms shown in this screenshot:
Live Demo #
For a live demo of adding custom data with even more examples, check out this recent talk by Luke Daley and Etienne Studer at the Bay Area Gradle Users meetup. The video starts with an overview of build scans and dives into the details of adding custom data around the 22:30 mark.
Adding custom data to your build scans gives you the power and flexibility to augment your build scans with tags, links, or other data tailored to your team’s specific needs. Then you have even more information available to easily share with your teammates in a build scan—reducing the guesswork of diagnosing build failures. Happy scanning!