aspect build & test - Aspect Build

aspect build and aspect test are the core CI tasks. They wrap bazel build and bazel test with environment configuration, live build progress in your CI platform, artifact upload, and a reproducer command for each failure. The command you run in CI works the same on a developer’s machine. If a build breaks, running aspect build --task:name build //... locally reproduces it.

What they do

aspect build builds Bazel targets. It:

Streams the Build Event Protocol (BEP) so features can observe each target’s outcome, timing and outputs.
Connects to a remote cache and build event service: from the runner’s environment on an Aspect Workflows CI runner, or from your default deployment with --remote elsewhere.
Retries on BLAZE_INTERNAL_ERROR (exit code 37) and LOCAL_ENVIRONMENTAL_ERROR (36), transient failures that don’t reflect your code.

aspect test does the same with bazel test, and adds:

Code coverage with LCOV output and an optional external tool.
Test log upload through ArtifactUpload, so failing test output is one click away in CI.

Environment configuration

On Aspect Workflows runners, the Workflows feature configures Bazel for the runner; see Aspect Workflows runners. To turn on remote execution there, set ctx.features[Workflows].args.remote_exec = True in config.axl. On any other CI runner, the Deployment feature connects the task to your default deployment, because --remote defaults to auto: on for CI when the job can authenticate, off elsewhere. See Aspect Cloud CI setup, and the built-in features reference for every feature’s options.

Options

Both tasks take these flags. aspect test adds the coverage flags.

Flag	Default	What it does
positional targets	`...`	Target patterns. `...` is every rule target in the package at and beneath the current directory. Separate hyphen-led patterns such as `-//experimental/...` from flags with `--`
`--target-pattern-file <path>`	none	Read newline-separated patterns from a file instead, like Bazel’s `--target_pattern_file`. Blank lines and `#` comments are ignored. Can’t be combined with patterns on the command line
`--bazel-retry-attempts <n>`	`3`	Maximum Bazel attempts, including the first, when Bazel exits with a transient error. `1` turns retries off
`--cancel`	off	Cancel any running Bazel invocation before starting
`--repro-flavor <flavor>`	`aspect`, `bazel`	Which reproducer commands to show on failure: `aspect`, `bazel` or both. Repeatable
`--bazel-flag <flag>`	none	A Bazel flag, for when one collides with a task flag. Repeatable
`--bazel-startup-flag <flag>`	none	A Bazel startup flag, for the same case. Repeatable
`--announce-bazel-rc`	`auto`	Print the resolved `.bazelrc` flags. `auto` prints on CI and stays quiet locally
`--announce-bazel-version`	`auto`	Print the detected Bazel version before each Bazel call
`--announce-bazel-command`	`auto`	Print the exact `bazel` command line before each Bazel call
`--bes-backend <uri>`	none	Extra Build Event Service backend the CLI streams to. Repeatable
`--bes-header <key=value>`	none	Header sent on every CLI-streamed BES stream. Repeatable

Configuration

Set options in .aspect/config.axl for every invocation, or with flags for one.

Targets

Pass target patterns as positional arguments:

aspect build //services/... //libs/...
aspect test //backend/...
aspect build -- //... -//experimental/...

Or set them in config.axl:

def config(ctx: ConfigContext):
    ctx.tasks["build"].args.targets = ["//services/...", "//libs/..."]

Bazel flags

Type Bazel flags directly. Each one the task doesn’t define is forwarded to Bazel: after the task name as a command option, before it as a startup option. See flag passthrough.

aspect build --config=remote --jobs=100 //...
aspect --host_jvm_args=-Xmx4g build //...

In config.axl, with conditional logic:

def config(ctx: ConfigContext):
    is_ci = bool(ctx.std.env.var("CI"))
    if is_ci:
        ctx.tasks["build"].args.bazel_flags = ["--config=remote", "--jobs=100"]

Test filters and coverage

# Run only integration tests, excluding slow ones
aspect test --test_tag_filters=integration,-slow //...

# Collect LCOV coverage and run genhtml
aspect test \
  --coverage \
  --coverage-report=coverage.dat \
  --coverage-tool=genhtml \
  --coverage-tool-arg=--output-directory=coverage-html \
  --coverage-tool-arg={report} \
  //...

Flag	Default	What it does
`--coverage`	off	Collect coverage. Adds `--collect_code_coverage` and `--combined_report=lcov`
`--coverage-report <path>`	none	Copy the merged LCOV report to this path
`--coverage-tool <bin>`	none	Run a tool against the merged report after the tests. It runs whatever the test result, and its exit code doesn’t fail the task
`--coverage-tool-arg <arg>`	none	An argument for the tool. Repeatable. `{report}` or `{lcov}` is replaced with the report path; with neither, the path is appended last

The merged report is read from $(bazel info output_path)/_coverage/_coverage_report.dat. The coverage flags have no effect without --coverage. For publishing to Codecov and per-provider CI examples, see Collect and publish code coverage.

GitHub status checks

The GithubStatusChecks feature posts a check run to the commit as soon as aspect build starts. It:

Creates the check run immediately, so the build shows as in progress.
Streams live progress: target counts and current failures.
Completes with pass or fail and a build summary with artifact download links.

It needs an Aspect credential: aspect-api-token on GitHub Actions, a Buildkite secret (secrets: [ASPECT_API_TOKEN]), ASPECT_API_TOKEN in the environment on GitLab and CircleCI. It also needs the Aspect Workflows GitHub App installed. Check names come from --task:name. Set a stable, distinct name on each invocation:

aspect build --task:name build //...
aspect test --task:name test //...

GitLab merge request status

These features post results to GitLab from merge request pipelines:

GitlabCommitStatuses: a commit status per task on the SHA under review, moving through pending, running, and success, failed, skipped or canceled as the task progresses.

A task reports aborted (🔥, exit 8) when Bazel is interrupted — Ctrl-C, or a CI runner cancelling the job. Running out of memory (exit 33) and losing the remote environment (exit 32) still report as failed. On GitLab aborted maps to canceled, not failed, so pipeline automation matching on failed will not match a cancelled job.

GitlabStatusComments: one merge request note with every task’s live status, updated as jobs finish.

They need the same Aspect credential, and the Aspect Workflows GitLab App linked to your Aspect account. They post only on merge request pipelines (where CI_MERGE_REQUEST_IID is set). Status names come from --task:name, as on GitHub. For linking the App and token roles, see GitLab App.

Artifact upload

ArtifactUpload uploads build outputs to your CI platform’s artifact storage. Every kind is opt-in, because artifacts are visible to anyone with repo access.

.aspect/config.axl

load("@aspect//feature/artifacts.axl", "ArtifactUpload")

def config(ctx: ConfigContext):
    ctx.features[ArtifactUpload].args.upload_test_logs = "failed"  # only failing tests
    ctx.features[ArtifactUpload].args.upload_profile   = True      # Bazel perf profile
    ctx.features[ArtifactUpload].args.upload_bep       = True      # Build Event Protocol log

Artifact	Option	When to use
Test logs	`upload_test_logs` (`none`/`failed`/`executed`/`all`)	Debug flaky tests; start with `failed`
Build logs	`upload_build_logs` (`none`/`failed`)	Debug failed build actions. Keep it off on public repos
Bazel profile	`upload_profile`	Performance analysis with `bazel analyze-profile`
Build Event Protocol	`upload_bep`	BES-based tooling. Environment variable values are redacted before upload
Compact execution log	`upload_exec_log`	Deep action investigation. Contains raw environment variables, so keep it off on public repos

With upload_build_logs = "failed", the stdout and stderr of every failed build action (compile, codegen, genrule and so on) are uploaded. Each log starts with a provenance header (# target, # action, # primary output, # stream) and lands under a path mirroring the target, such as foo/bar/baz/Genrule.stderr.log for //foo/bar:baz. Same-mnemonic actions under one target are told apart by the primary output’s basename. GitHub and GitLab status checks then show a Build logs link next to Test logs. It applies wherever Bazel runs: build, test, run, warming, gazelle, format, lint and delivery. ArtifactUpload uses the runner’s own CI credentials (permissions: id-token: write on GitHub Actions, the agent token on Buildkite, CI_JOB_TOKEN on GitLab). It doesn’t need ASPECT_API_TOKEN.

CI example

.github/workflows/ci.yaml

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read    # actions/checkout
  id-token: write   # artifact uploads and the PR summary comment

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - run: aspect build --task:name build -- //...

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - run: aspect test --task:name test -- //...

Complete pipeline examples shows the same setup on Buildkite, GitLab CI and CircleCI, and on Aspect Workflows CI runners.

​What they do

​Environment configuration

​Options

​Configuration

​Targets

​Bazel flags

​Test filters and coverage

​GitHub status checks

​GitLab merge request status

​Artifact upload

​CI example

What they do

Environment configuration

Options

Configuration

Targets

Bazel flags

Test filters and coverage

GitHub status checks

GitLab merge request status

Artifact upload

CI example