Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

Aspect Workflows manages the execution of Bazel’s build and test commands through dedicated tasks configured in the .aspect/workflows/config.yaml file. This architecture provides control over which targets to build or test, how to apply flags, and how to generate coverage reports. This document explains the core concepts of configuring these tasks and the hierarchical rules for managing Bazel flags.

​
The build and test task basics

The test task executes bazel test and the build task executes bazel build.
  • Default Execution: The simplest configuration runs all tests or builds all targets in the workspace, equivalent to bazel test //... or bazel build //....
  • Target Specification: You can specify exact targets or patterns using the targets: attribute, which is a list of patterns.
  • Target Exclusion: Use the negative pattern with a minus sign within the targets: list to exclude specific sub-packages or targets from the task’s scope.

​
Use case for a separate build task

A dedicated build task is useful in specific scenarios:
  • Partial Builds: When you pass the --build_tests_only flag to Bazel, the test task won’t build targets that aren’t dependencies of any tests.
  • Non-Executable Tests: You can use a build task to compile tests without running them, which is useful if some test targets have known issues but still need compilation.

​
Code coverage integration

To enable code coverage, you set the coverage attribute to true on the test task. Workflows handles the underlying complexity by running bazel test with the necessary equivalent flags, avoiding the need for the user to directly invoke bazel coverage.
.aspect/workflows/config.yaml
    tasks:
    - test:
        coverage: true

​
Hierarchical Bazel flag management

Aspect Workflows allows you to configure Bazel flags at two levels: top-level and task-level. The general recommendation is to check common Bazel flags into a .bazelrc file.
Workflows automatically looks for and uses a Bazel Resource Control file at .aspect/workflows/bazelrc. If this file is present, Workflows passes --bazelrc=.aspect/workflows/bazelrc to every Bazel invocation.

​
Flag in config.yaml file

You can also place flags directly in the config.yaml file:
  • Top-level: Under the global bazel: flags: attribute, applying to all tasks.
  • Task-level: Under a specific task’s bazel: flags: attribute, for example within a test: task.
Flag overriding logic: flags specified at the task level override the list set at the top level. They’re not merged.

​
Bazel startup flag management

Startup flags—which control the Bazel server itself, for example --noworkspace_rc—require specification as command-line flags and follow similar management patterns as regular Bazel flags.
  • Location: You place startup flags under the bazel: startup_flags: attribute at either the top-level for all tasks or the task-level for a specific task.
  • Overriding Logic: Just like regular Bazel flags, task-level startup flags override the top-level list and aren’t merged.

​
Build event stream backend configuration

The Build Event Stream allows external services to receive build and test data. Since Bazel supports only a single Build Event Stream backend and Workflows occupies the default endpoint, you must explicitly configure an alternative endpoint. You set the Build Event Stream backend value using the --bes_backend=<url> flag.
Setting this flag instructs the Aspect command-line tool, which runs the Workflows runners, to forward the Build Event Stream data to the specified alternative backend.