This guide explains how to configure Bazel builds to create Build Scans with Gradle Enterprise.

Gradle Enterprise Build Scans provide observability of build and test results in your web browser. They help collaboratively debug build problems and optimize build performance.

Gradle Enterprise 2021.4 or later is required to use Build Scans for Bazel builds.

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

Getting set up

To publish Build Scans to your Gradle Enterprise server, add the following to the .bazelrc file in your build workspace.

build --bes_backend=grpcs://«gradle-enterprise-server»
build --bes_results_url=https://«gradle-enterprise-server»/build/

Replacing «gradle-enterprise-server» with the hostname of your server. If you use a non standard port for HTTPS traffic, this must also include the port number.

This configuration can also be specified on the command line as part of the build invocation, or via other mechanisms that Bazel provides. Please see the Bazel documentation for more information.

At the beginning and end of your build, you will see output similar to:

INFO: Streaming build results to: https://«gradle-enterprise-server»/build/66e6805b-7ce1-4e32-bc26-c0fa129c76a7

The link shown is your Build Scan link and can be used to observe the results of the build.

Using a Bazel remote cache

Bazel Build Scans provide more information when the build uses a remote cache that is also accessible by the Gradle Enterprise server.

Bazel uploads build artifacts, test results and diagnostic information to the remote cache. When Build Scans are published to Gradle Enterprise, such diagnostic information is read from the remote cache and included in Build Scans. This allows Build Scans to provide more information about the build. In particular, action profile information and detailed test results are included.

When viewing Build Scans, the build artifacts and diagnostic logs of targets and failed actions can be downloaded from the user interface if the remote cache is accessible.

For a remote cache to be accessible by Gradle Enterprise, it must support the gRPC protocol and allow anonymous read access.

Setting the Project ID

Gradle Enterprise allows analyzing sets of builds based on search criteria. It is useful to use Bazel’s --project_id configuration option to set a well known name for the project to allow for more effective searching. If this option is not present, the directory name of the build workspace will be used as the project ID.

Consider setting a --project_id value in your workspace .bazelrc file.

Extending Build Scans

You can easily include extra 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.

Such information is included by using Bazel’s workspace status and/or build metadata mechanisms, with specific value name prefixes.

The workspace status mechanism is most appropriate when a tag, value or link needs to be computed. The build metadata mechanism can be used when it is static, or is specified as part of the command line invocation.

Tags, values and links use the following prefixes respectively:

  • SCAN_TAG_

  • SCAN_VALUE_

  • SCAN_LINK_

The following are examples of creating a tag, value and link using build metadata at build invocation time:

bazel build ... \
--build_metadata=SCAN_TAG_LOCAL_BUILD= \
--build_metadata=SCAN_VALUE_GIT_COMMIT_ID=$(git rev-parse HEAD) \
--build_metadata=SCAN_LINK_CI_BUILD=https://ci-server.company.com/build/${BUILD_ID}

The workspace status mechanism works by running a program that prints status item values to stdout. The following is an example of using a shell script named scan_data.sh in the workspace directory to create a tag, value and link:

scan_data.sh 
#!/bin/sh
echo SCAN_TAG_LOCAL_BUILD ""
echo "SCAN_VALUE_GIT_COMMIT_ID $(git rev-parse HEAD)"
echo "SCAN_LINK_CI_BUILD https://ci-server.company.com/build/${BUILD_ID}"

This script must be specified as a workspace status command, which is typically achieved by adding the following to the workspace .bazelrc file.

.bazelrc 
build --workspace_status_command=$(pwd)/scan_data.sh