Skip to main content
Bazel emits a stream of structured events during every build: target outcomes, test results, output file paths, timing, and more. An AXL task can read the stream as it arrives, upload it to a backend, and write it to a file. Pass any mix of these handles to ctx.bazel.build() or ctx.bazel.test() in the build_events list: Every handle sees the same stream, with secrets redacted: credentials in URLs, the values of header flags such as --remote_header and --bes_header, and the values of --action_env, --test_env, --repo_env and similar flags. Common CI variables pass through; extend that list with --build_metadata=ALLOW_ENV=NAME,OTHER_*.
Build Event Stream reference

Iterate events

Create an iterator, pass it in build_events, and loop over it. The loop blocks until the next event arrives and ends when the build finishes. Each event has a kind string naming the event type, and a payload whose fields depend on that kind.

Collecting output files

Output files arrive in named_set_of_files events:
The File payload exposes name, digest, length, and path_prefix directly. The URI is wrapped in a file oneof (uri, contents, or symlink_target_path). name is the file’s logical identifier and carries no directory prefix; the output-tree path is path_prefix joined with name — "/".join(file.path_prefix) + "/" + file.name.

Filtering by event kind

Pass kinds= to deliver only the listed event kinds:

Reacting to test results

test_result events fire once per test target. The target’s label is on the event’s id, and the status is on the payload:
See the test_result payload reference for the full list of fields.

Upload to a BES backend

A gRPC sink streams the build’s events to a Build Event Service backend, the same protocol Bazel’s own --bes_backend speaks:
To upload without writing AXL, pass --bes-backend=<uri> to aspect build, aspect test or another built-in task that takes it, with --bes-header=<name>=<value> for headers. Both repeat. For an Aspect backend you’re logged in to, the CLI attaches your login unless you pass an authorization header. A backend Bazel already uploads to through its own --bes_backend is skipped, so the build is streamed there once.

Write the stream to a file

A file sink writes the events to path as length-delimited BuildEvent messages, the format of Bazel’s --build_event_binary_file:
The file is complete once wait() has returned.

Wait for sinks

A sink’s outcome doesn’t change the build’s status. Call wait() on each sink after build.wait(), then read its outcome: wait() also frees the sink for a later build. wait(timeout_ms = ...) returns False if the sink is still running after that long, and leaves it running for a later wait().

Add sinks to the built-in tasks

Built-in tasks that stream build events, such as aspect build, aspect test and aspect lint, pass the sinks in BazelTrait.build_event_sinks to their builds and wait for them. Append to it from .aspect/config.axl:
A fixed path like this holds the last build’s events.