Skip to main content
Version: 5.8.x


Workflows provides a simple DSL to configure the CI/CD pipeline, focused on Bazel-centric tasks.

Workflows expects the configuration file to be checked into the source repository. The default location is /.aspect/workflows/config.yaml.

An example configuration file looks like this:

# Checks that the branch is current
# Rebase PR changes on main, to avoid churning the repository cache
update_strategy: rebase
# Checks that BUILD file content is up-to-date with sources
# Checks that all tests are passing
coverage: true
# These flags are guaranteed to come after those added by Rosetta,
# so we are sure to override them.
# Most flags belong in your .bazelrc file.
# Allow tests to fetch private container images from dockerhub
- --test_env=DOCKER_USERNAME
- --test_env=DOCKER_PASSWORD
- //...
- -//experimental/...

See the API documentation for information on all top level configuration options, or see the Tasks list for a list of available tasks.


By default, Workflows will run tasks in the workspace at the root of the repository. If required, it is possible to configure multiple workspaces in the same repository, or set the default to a nested directory. Workspaces are defined by setting the workspaces configuration option.

Tasks defined at the root of the configuration apply to all workspaces, unless specifically overriden.

Single workspace

A single workspace of . (the repository root) is defined by default when no workspaces option is given. There is no need to define a workspace at . if it is the only workspace Workflows will run for.

The default workspace can be changed by setting a single item in the workspaces option. In the example below, this moves the default workspace to src/examples:

- src/examples
tasks: ...

Multiple workspaces

Workflows can run tasks across multiple Bazel workspaces. To define multiple workspaces, add the paths to the workspaces configuration option.

In the example below, three workspaces are defined, one at the root of the repository, one in third_party/library and another in src/examples. Workflows will run the tasks defined by tasks for all workspaces.

- .
- third_party/library
- src/examples
tasks: ...

Overriding configuration for a workspace

Configuration options may be overriden per workspace. The list of tasks at the root are merged with the task list defined on each workspace. For example, to run a different gazelle check and fix target for each non-default workspace:

- .
- src/examples:
target: //gazelle:example_check
target: //gazelle:check

The full configuration options for workspaces can be found in the API documentation.


The API documentation for the config file is in the configuration API doc. We're working on improving the exhaustive API documentation for Workflows!