Build Results UI repository setup

The Build Results UI reads build metadata to label each invocation, and Bazel flags decide how much of the profile, artifacts, and execution log reach it. Both live in your repository, the same on Aspect Cloud and Aspect Enterprise.

Build metadata

The Build Results UI reads specific metadata keys to fill fields such as Branch, Author, Task, and CI Host, and the matching feed filters. Aspect CLI tasks and Aspect Workflows CI runners set most of these automatically. For vanilla bazel, the quickest setup is to have the Aspect CLI print them. Add one line to your .bazelrc:

.bazelrc

build --workspace_status_command="aspect setup workspace-data"

If you already have a workspace status script, call it from inside that script instead, since Bazel takes one status command:

if command -v aspect > /dev/null 2>&1; then
  aspect setup workspace-data
fi

It reads the commit, branch, pull request, actor, repository and CI run from the environment and prints the matching keys. See aspect setup workspace-data for the keys it emits and how it composes with your own. To set the keys yourself, without the Aspect CLI or for keys it doesn’t cover, use Bazel’s —build_metadata or —workspace_status_command flags. The UI reads a key from either source.

Recommended keys

Key	Description
`ASPECT_TASK_NAME`	The name of the Aspect CLI task. Outside a task, use the Bazel command you ran.
`ASPECT_TASK_ID`	The unique identifier of the Aspect CLI task. Outside a task, use the Bazel command you ran.
`ASPECT_TASK_URL`	A link to the Aspect CLI task’s CI job. Outside a task, link to the build you ran.
`USER`	The user or entity that initiated the build.
`BRANCH_NAME`	The git branch name.
`REPO_NAME`	The name of the git repository.
`REPO_OWNER`	The owner/organization of the git repository.
`COMMIT_SHA`	The full commit hash.
`COMMIT_MESSAGE`	The commit message.
`COMMIT_AUTHOR_NAME`	The git commit author name.
`COMMIT_AUTHOR_EMAIL`	The git commit author email.
`COMMIT_AUTHOR`	The git commit author information. Often formatted from git as: `Some User <user@company.email>`.
`VCS`	The version control system being used. Valid options are: `GITHUB`, `GITLAB`
`CI_HOST`	The CI provider. Valid options are: `BUILDKITE`, `CIRCLE_CI`, `GITHUB_ACTIONS`, `GITLAB`.
`RUN_TYPE`	The type of CI run. If it’s unset, the UI treats the build as a local Bazel build. Valid options are: `PULL_REQUEST`, `BRANCH_PUSH`, `TAG`, `SCHEDULED`, `MANUAL`.
`BUILD_URL`	A link to the CI build (if applicable).
`COMMIT_TAG`	The git tag that caused a CI run (if applicable). Aspect CLI tasks record the tag as `TAG`, which the UI doesn’t read, so set `COMMIT_TAG` yourself to show it.
`PR_NUMBER`	The Pull Request number (if applicable).
`PR_ID`	The Pull Request id (if applicable).
`PR_SOURCE_BRANCH_NAME`	The source branch from a given pull request (if applicable).
`PR_TARGET_BRANCH_NAME`	The target branch from a given pull request (if applicable).

Workspace status command

To set other keys, or to work without the Aspect CLI, write a --workspace_status_command script that generates them from your CI environment variables. Create a script:

workspace_status.sh

#!/usr/bin/env bash
echo ASPECT_TASK_NAME "Test"
echo ASPECT_TASK_ID "test"
echo ASPECT_TASK_URL "https://ci.example.com/builds/123"
echo USER "First Last"
echo BRANCH_NAME "feature/some-branch"
echo REPO_NAME "some-repo"
echo REPO_OWNER "some-org"
echo COMMIT_SHA "b6d171bbcfb54c77ce5fc165b778d2c25bbef87b"
echo COMMIT_MESSAGE "feat: some awesome change"
echo COMMIT_AUTHOR_NAME "Some User"
echo COMMIT_AUTHOR_EMAIL "user@company.email"
echo COMMIT_AUTHOR "Some User <user@company.email>"
echo VCS "GITHUB"
echo CI_HOST "BUILDKITE"
echo RUN_TYPE "PULL_REQUEST"
echo BUILD_URL "https://ci.example.com/builds/123"
echo PR_NUMBER "456"
echo PR_ID "456"
echo PR_SOURCE_BRANCH_NAME "feature/some-source-branch"
echo PR_TARGET_BRANCH_NAME "feature/some-target-branch"

Configure Bazel to use this script in your .bazelrc or specify it via the command line:

bazel build //... --workspace_status_command=./workspace_status.sh

Build metadata flags

Set the same keys with --build_metadata flags instead of, or alongside, a workspace status script.

bazel build //... \
  --build_metadata="ASPECT_TASK_NAME=Test" \
  --build_metadata="ASPECT_TASK_ID=test" \
  --build_metadata="ASPECT_TASK_URL=https://ci.example.com/builds/123" \
  --build_metadata="USER=First Last" \
  --build_metadata="BRANCH_NAME=feature/my-branch" \
  --build_metadata="REPO_NAME=some-repo" \
  --build_metadata="REPO_OWNER=some-org" \
  --build_metadata="COMMIT_SHA=b6d171bbcfb54c77ce5fc165b778d2c25bbef87b" \
  --build_metadata="COMMIT_MESSAGE=feat: some awesome change" \
  --build_metadata="COMMIT_AUTHOR_NAME=Some User" \
  --build_metadata="COMMIT_AUTHOR_EMAIL=user@company.email" \
  --build_metadata="COMMIT_AUTHOR=Some User <user@company.email>" \
  --build_metadata="VCS=GITHUB" \
  --build_metadata="CI_HOST=BUILDKITE" \
  --build_metadata="RUN_TYPE=PULL_REQUEST" \
  --build_metadata="BUILD_URL=https://ci.example.com/builds/123" \
  --build_metadata="PR_NUMBER=456" \
  --build_metadata="PR_ID=456" \
  --build_metadata="PR_SOURCE_BRANCH_NAME=feature/some-source-branch" \
  --build_metadata="PR_TARGET_BRANCH_NAME=feature/some-target-branch"

Aspect CLI tasks

Aspect CLI tasks set the ASPECT_TASK_* keys themselves. To change the task name the UI shows, pass --task:name or --task:friendly-name to the task. To add another key to every task’s invocations, append a --build_metadata flag in config.axl, as in the ALLOW_ENV example below.

Redacted environment variables

The Build Results UI redacts environment variables in the command line and options it displays, since flags can carry secrets. To display specific variables, list them in the ALLOW_ENV key. Set the key in your workspace status script or with a build metadata flag. The value is a comma-separated list of environment variable names or patterns. If both set it, the build metadata value wins.

Example using build metadata

bazel build //... --build_metadata="ALLOW_ENV=USER,PATH,TZ,LANG,LC_*,BAZEL_*,RUST_*,JAVA_*"

Example using workspace status

#!/usr/bin/env bash
# ... other status variables ...
echo ALLOW_ENV "USER,PATH,TZ,LANG,LC_*,BAZEL_*,RUST_*,JAVA_*"

Example using config.axl

.aspect/config.axl

load("@aspect//traits.axl", "BazelTrait")

def config(ctx: ConfigContext):
    ctx.traits[BazelTrait].extra_flags.extend([
        "--build_metadata=ALLOW_ENV=USER,PATH,TZ,LANG,LC_*,BAZEL_*,RUST_*,JAVA_*",
    ])

Bazel flags for the deeper views

Bazel’s defaults omit much of the data the Build Results UI’s deeper views are built from. The profile is slimmed and has no target labels, artifact listings come back empty, and the execution log, the source for per-target dependencies, is never produced. Enable the following flags to populate the Timing tab’s profile views, the Artifacts tab, and target dependency expansion. The execution log and profile reach the UI through the remote cache, so the build also needs a gRPC --remote_cache.

Workflows 6.0 or later is required. On 5.18 the flags are harmless but have nothing to populate: the legacy UI has no Artifacts tab or dependency expansion. See the .

Flag	What it enables in the UI	Overhead
`--profile=command.profile.gz`	Pins the profile’s file name to the one the UI ingests.	None.
`--noslim_profile`	The complete build profile. By default Bazel slims the profile, merging or dropping short actions, which hides the true critical path.	Minor. Produces a larger profile file.
`--experimental_profile_include_target_label`	Target labels on profile actions, so the timeline maps back to the targets that produced it.	Minor.
`--experimental_profile_include_primary_output`	The primary output path on each profile action, so an entry names the file it produced.	Minor.
`--experimental_profile_include_target_configuration`	The configuration each profile action was built in.	Minor.
`--execution_log_compact_file=exec.log.zst`	Expandable per-target dependencies, and the remote cache hit rate on the Cache tab. Without it, a target’s dependencies stay empty. The compact format is the only one the UI ingests.	Writes one zstd-compressed execution log per invocation.
`--remote_build_event_upload=all`	Uploads every file the BEP references, not just the remotely cacheable ones, so the UI can serve them.	Additional CAS uploads.
`--experimental_build_event_upload_strategy=remote`	Uploads BEP-referenced files to the remote CAS and references them from the event stream, which is how the execution log reaches the UI.	Shifts upload work to the CAS and keeps the BEP itself small.
`--legacy_important_outputs`	The Artifacts tab and artifact downloads. A modern Bazel client omits `important_outputs` from the BEP, so the tab is otherwise empty.	The largest of the set: it re-inflates `important_outputs` on every target-complete event. Leave it off if BEP volume is a concern.

On a self-hosted Aspect Enterprise deployment, the Artifacts tab can list a target’s full output set instead of its important outputs, which is a deployment setting. See .

Using `.bazelrc`

Add the flags to your workspace .bazelrc. Scoping them to a ci config keeps the extra profiling work off local developer builds:

.bazelrc

common:ci --profile=command.profile.gz
common:ci --noslim_profile
common:ci --experimental_profile_include_target_label
common:ci --experimental_profile_include_primary_output
common:ci --experimental_profile_include_target_configuration
common:ci --execution_log_compact_file=exec.log.zst
common:ci --remote_build_event_upload=all
common:ci --experimental_build_event_upload_strategy=remote
common:ci --legacy_important_outputs

Then pass --config=ci on CI invocations. To apply the flags everywhere, including local builds, drop the :ci suffix and use plain common lines.

Using `.aspect/config.axl`

If you use the Aspect CLI, set the flags in .aspect/config.axl instead. This applies them only when the CI environment variable is set, so no --config=ci plumbing is needed in your pipeline:

.aspect/config.axl

load("@aspect//traits.axl", "BazelTrait")

def config(ctx: ConfigContext):
    is_ci = bool(ctx.std.env.var("CI"))
    if is_ci:
        ctx.traits[BazelTrait].extra_flags.extend([
            "--profile=command.profile.gz",
            "--noslim_profile",
            "--experimental_profile_include_target_label",
            "--experimental_profile_include_primary_output",
            "--experimental_profile_include_target_configuration",
            "--execution_log_compact_file=exec.log.zst",
            "--remote_build_event_upload=all",
            "--experimental_build_event_upload_strategy=remote",
            "--legacy_important_outputs",
        ])

Measuring the overhead

The cost of these flags depends on the shape of your build: the number of targets, the size of the output set, and how much of the build is already cached. Enable them on a branch and use the UI’s Compare page to measure two runs of the same task against each other. If the overhead is too high, drop --legacy_important_outputs first. The profiling flags are the cheapest to keep.

​Build metadata

​Recommended keys

​Workspace status command

​Build metadata flags

​Aspect CLI tasks

​Redacted environment variables

​Example using build metadata

​Example using workspace status

​Example using config.axl

​Bazel flags for the deeper views

​Using .bazelrc

​Using .aspect/config.axl

​Measuring the overhead

Build metadata

Recommended keys

Workspace status command

Build metadata flags

Aspect CLI tasks

Redacted environment variables

Example using build metadata

Example using workspace status

Example using config.axl

Bazel flags for the deeper views

Using `.bazelrc`

Using `.aspect/config.axl`

Measuring the overhead