Build and Test UI

If you are running Bazel or other build tools locally, your build and test results are just output to your console.

EngFlow’s Build and Test UI lets you:

• find out why your Bazel builds and tests fail,
• share your build and test results with others for debugging,
• review historical data to discover trends,
• and analyze your runs to optimize your builds and tests.

If you are using EngFlow Remote Execution, you can use the Build and Test UI out of the box by logging in to your cluster at your cluster-specific <CLUSTER_ENDPOINT>.

You can also send your build data to the Build and Test UI without Remote Execution by forwarding the Build Event Protocol (BEP) with the following Bazel flags, replacing <CLUSTER_ENDPOINT> appropriately:

bazel build \
  --bes_backend=grpcs://<CLUSTER_ENDPOINT> \
  --bes_results_url=https://<CLUSTER_ENDPOINT>/invocation/ \
  //...

Also see the page on Bazel First-Time Setup and setting up .bazelrc.

Info

The UI exposes information about your build, potentially including source code.

Adding additional data to invocations

You can add supplemental data to your invocations to more easily identify them in EngFlow’s Build and Test UI.

The above screenshot shows part of an invocation’s summary that includes the following additional data:

1. Source control management system
2. CI system
3. BES keywords

Source control management system

You can add metadata about the source control management (SCM) system used. We currently support four data points:

• Repository
• Branch
• Commit Id
• Whether there are local changes on top of the commit

This metadata can be provided either by setting SCM-specific BES keywords, or via the workspace status. If both methods are used, the BES keywords take precedence over the workspace status keys.

SCM-specific BES Keywords

For EngFlow v2.72.0 and above, you can provide metadata on the source control management system via BES keywords. Add the following command-line flags to your Bazel invocation, replacing <REPOSITORY_URI>, <BRANCH_NAME> and <COMMIT_ID> appropriately:

• --bes_keywords=engflow:BuildScmRemote=<REPOSITORY_URI> for the repository
• --bes_keywords=engflow:BuildScmBranch=<BRANCH_NAME> for the branch
• --bes_keywords=engflow:BuildScmRevision=<COMMIT_ID> for the commit
• To indicate whether there are local changes on top of the commit:
  • --bes_keywords=engflow:BuildScmStatus=modified for changes
  • --bes_keywords=engflow:BuildScmStatus=clean for no changes

Here's a concrete example for building source code hosted on GitHub:

bazel build \
  --bes_keywords=engflow:BuildScmRemote=https://github.com/EngFlow/engflowapis \
  --bes_keywords=engflow:BuildScmBranch=main \
  --bes_keywords=engflow:BuildScmRevision=e2a48922b7db50eb57bb0cfe18fb4b216d9133d0 \
  --bes_keywords=engflow:BuildScmStatus=modified \
  //...

Workspace status

Using the Bazel flag --workspace_status_command you can specify a command to invoke at the beginning of each build to provide status information. See the Bazel’s user manual for more information and the bazelbuild/bazel GitHub repo for an example script.

EngFlow recognizes and surfaces the following workspace status keys in the Build and Test UI:

• BUILD_SCM_REMOTE for the repository
• BUILD_SCM_BRANCH for the branch
• BUILD_SCM_REVISION for the commit
• BUILD_SCM_STATUS to indicate whether there are local changes on top of the commit

Below in an example script for git users that populates all of the above:

echo BUILD_SCM_BRANCH $(git rev-parse --abbrev-ref HEAD)
echo BUILD_SCM_REVISION $(git rev-parse --verify HEAD)

git diff-index --quiet HEAD --
if [[ $? == 0 ]]; then
  status="clean"
else
  status="modified"
fi
echo BUILD_SCM_STATUS $status

REMOTE=$(git remote)
REMOTE_URL=$(git remote get-url $REMOTE)
if [[ $? == 0 ]]; then
  echo BUILD_SCM_REMOTE $REMOTE_URL
fi

CI system

You can specify details about invocations run as part of your CI setup. For this, add some Bazel flags to your invocations, replacing <PIPELINE_NAME>, <JOB_NAME> and <URI> appropriately:

bazel build \
  --bes_keywords=engflow:CiCdPipelineName=<PIPELINE_NAME> \
  --bes_keywords=engflow:CiCdJobName=<JOB_NAME> \
  --bes_keywords=engflow:CiCdUri=<URI> \
  //...

Additionally, you may specify the user that triggered a build in CI. Add the following Bazel flag to your invocations replacing <USER_PRINCIPAL> with the identifier of the user that triggered the build (such as alice@engflow.com):

bazel build \
  --bes_keywords=engflow:Requester=<USER_PRINCIPAL> \
  //...

Info

BES keywords that start with the prefix engflow: are specially handled by EngFlow, in this case to surface details about the CI system used.

BES keywords

You can tag your invocations flexibly by using BES keywords.

For this, use the Bazel flag --bes_keywords. Multiple uses are accumulated:

bazel build \
  --bes_keywords=foo \
  --bes_keywords=bar \
  //...

Info

On the invocations page you can filter invocations by those that include specific BES keywords.

Warning

BES keywords that start with the prefix engflow: are specially handled by EngFlow and not added to the invocation search index. They are either not surfaced in the UI at all, or handled separately. See CI system for an example.