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
- Protocol definition: build_event_stream.proto
- API documentation: Buf Schema Registry
- Event ordering examples: Bazel BEP Documentation
- AXL type reference: build_event kinds, BuildEventSink
Iterate events
Create an iterator, pass it inbuild_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 innamed_set_of_files events:
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
Passkinds= 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:
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 topath as length-delimited BuildEvent messages, the format of Bazel’s --build_event_binary_file:
wait() has returned.
Wait for sinks
A sink’s outcome doesn’t change the build’s status. Callwait() 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 asaspect 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:

