aspect build and aspect test

aspect build and aspect test run Bazel builds and tests from your CI pipeline. On an Aspect Workflows runner, the runner’s cache, BES endpoint and output paths are injected by the Workflows feature. GitHub status checks are posted by the GithubStatusChecks feature. Artifact uploads are handled by the ArtifactUpload feature.

Task-level retry, timeout, and conditional execution are now handled by your CI platform rather than the task runner. Bazel’s internal retry for transient errors (e.g. BLAZE_INTERNAL_ERROR, LOCAL_ENVIRONMENTAL_ERROR) is still built into the CLI.

What changed

Area	YAML-configured tasks	Aspect CLI tasks
Invocation	`bazel build` / `bazel test` via task runner	`aspect build` / `aspect test`
Targets	`targets:` in `.aspect/workflows/config.yaml` (default `//...`)	positional args (default `...`)
Bazel flags	`bazel.flags` / `bazel.startup_flags` in `.aspect/workflows/config.yaml`	`--bazel-flag` / `--bazel-startup-flag`
BES / remote cache	Auto-configured from platform config	Injected by the `Workflows` feature on a runner
GitHub status checks	Built into task runner	`GithubStatusChecks` feature
Artifact upload	Built into task runner	`ArtifactUpload` feature (opt-in per artifact kind)
Internal error retry	Bazel retries 3× on transient errors	Up to 3 attempts on `BLAZE_INTERNAL_ERROR` / `LOCAL_ENVIRONMENTAL_ERROR` (`--bazel-retry-attempts`)
Task timeout	`timeout_in_minutes` in `.aspect/workflows/config.yaml`	CI platform job/step timeout
Lifecycle hooks	`before_task` / `after_task` hooks	CI platform steps
Conditional execution	`when:` expressions	CI platform conditionals
Workspaces	`workspaces:` top-level list (one or more directories)	`cd <dir>` in your CI config; run `aspect <task>` from there

Configuration

Most settings below can be applied either way:

CLI flag: pass the flag at invocation time (e.g. aspect build --bazel-flag=--config=remote //...). Good for overrides on individual task invocations, or experimenting with a setting before committing it.
.aspect/config.axl: declare it once in your repo’s AXL config so every aspect build / aspect test invocation picks it up. Good for settings that should apply to all invocations of a task type. AXL can also compute values (e.g. branching on CI host or environment).

Pick whichever fits; you only need one. Where both work, the sections below show them side-by-side under After.

Targets

Before: .aspect/workflows/config.yaml:

tasks:
  build:
    targets:
      - //services/...
      - //libs/...

After: positional CLI args or config.axl:

aspect build //services/... //libs/...

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

The default (no arguments) is ..., which expands to all rule targets in the package at and beneath your current directory.

Bazel flags

Before: .aspect/workflows/config.yaml:

tasks:
  build:
    bazel:
      flags:
        - --config=remote
        - --jobs=100
      startup_flags:
        - --host_jvm_args=-Xmx4g

After: CLI flag or config.axl:

aspect build \
  --bazel-flag=--config=remote \
  --bazel-flag=--jobs=100 \
  --bazel-startup-flag=--host_jvm_args=-Xmx4g \
  //...

def config(ctx: ConfigContext):
    ctx.tasks["build"].args.bazel_flags = ["--config=remote", "--jobs=100"]
    ctx.tasks["build"].args.bazel_startup_flags = ["--host_jvm_args=-Xmx4g"]

Test tag filters

Before: .aspect/workflows/config.yaml:

tasks:
  test:
    filters:
      - integration
      - -slow

After: CLI flag or config.axl:

aspect test --bazel-flag=--test_tag_filters=integration,-slow //...

load("@aspect//traits.axl", "BazelTrait")

def config(ctx: ConfigContext):
    ctx.traits[BazelTrait].extra_flags.append("--test_tag_filters=integration,-slow")

Code coverage

Before: .aspect/workflows/config.yaml:

tasks:
  test:
    coverage: true

After: CLI flag or config.axl:

aspect test --coverage //...

def config(ctx: ConfigContext):
    ctx.tasks["test"].args.coverage = True

--coverage adds --collect_code_coverage and --combined_report=lcov. --coverage-report copies the merged LCOV report to a path, and --coverage-tool runs an uploader against it. See Code coverage.

Test log upload

Before: .aspect/workflows/config.yaml:

tasks:
  test:
    upload_test_logs: failed

After: CLI flag or config.axl:

aspect test --artifact-upload:upload-test-logs=failed //...

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

def config(ctx: ConfigContext):
    ctx.features[ArtifactUpload].args.upload_test_logs = "failed"

Upload strategies: none (default), failed, executed, all. Test log upload is one knob of the broader Artifact upload feature; see that section for the full list of artifact kinds and authentication requirements.

GitHub status checks

The legacy YAML-configured tasks posted build and test results to a PR comment via the Aspect Workflows GitHub App. There was no per-task GitHub status check. The new Aspect CLI posts a GitHub status check for each aspect build / aspect test invocation via the GithubStatusChecks feature. The feature is on by default and posts checks once the CLI is authenticated with an Aspect credential and the Aspect Workflows GitHub App is installed. GithubStatusChecks:

Creates a check run on the commit as soon as the task starts
Updates it with live build progress (target counts, failures) during the build
Completes it with a pass/fail conclusion and a build summary including artifact download links

Set —task:name explicitly on any invocation that uses GithubStatusChecks or ArtifactUpload. Status check names and uploaded artifact names are derived from the task name, so a stable, distinct value per invocation makes results identifiable (e.g. build, test). Without it, on CI the name is derived from the CI job name: renaming the CI job renames the check, and the shards of a GitHub Actions matrix all get the same name. Off CI it’s random per run.

Authentication

GithubStatusChecks 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.
The Aspect Workflows GitHub App installed on the GitHub org/repository and linked to your Aspect account, so the CLI can use the App to post the check.

See the GitHub App page for installing and linking the app, and Authenticating the Aspect CLI for generating the API token.

Troubleshooting

If no check appears, search the build log for GitHub status checks:. A missing credential logs one line per task naming what’s missing, for example on GitLab or CircleCI:

GitHub status checks: Authentication failed for acme/widgets — no Aspect credentials — set ASPECT_API_TOKEN (an API token from the Aspect Web UI) in the job env. Setup guide: https://aspect.build/docs/cli/authentication

Artifact upload

The ArtifactUpload feature uploads build artifacts to the CI platform. All upload kinds are opt-in (off by default) because uploaded artifacts are accessible to anyone with repo read access.

On public repositories, uploaded artifacts are downloadable by anyone on the internet. Treat every upload kind as public-by-default and double-check the risk column below before enabling anything.

Artifact	Flag	Risk
Test logs	`--artifact-upload:upload-test-logs=failed`	Medium: test output can leak CI secrets if a test prints, asserts on, or otherwise emits values from env vars (e.g. tokens, API keys)
Build logs	`--artifact-upload:upload-build-logs=failed`	High: compiler / codegen stderr can echo env-var values from action command lines (including secrets); keep off on public repositories
Bazel profile	`--artifact-upload:upload-profile=true`	Low: labels and file paths only
Build Event Protocol	`--artifact-upload:upload-bep=true`	Low: the CLI redacts env-var values that may hold secrets or sensitive data before upload
Compact execution log	`--artifact-upload:upload-exec-log=true`	High: contains raw action env vars (including secrets); keep off on public repositories

Build logs (upload_build_logs, values none / failed, default none) upload the full stdout and stderr of every failed build action to CI artifacts, the non-test counterpart to upload_test_logs. Each log has a provenance header (# target, # action, # primary output, # stream) and a target-based archive path (e.g. foo/bar/baz/Genrule.stderr.log). When enabled, GitHub / GitLab status checks surface a Build logs link alongside the existing Test logs link. Enable permanently in config.axl:

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

def config(ctx: ConfigContext):
    ctx.features[ArtifactUpload].args.upload_test_logs = "failed"
    ctx.features[ArtifactUpload].args.upload_profile   = True

ArtifactUpload does not use the Aspect Workflows GitHub App or ASPECT_API_TOKEN. It uploads to your CI platform’s native artifact storage using the runner’s own credentials: permissions: id-token: write on GitHub Actions, the Buildkite agent token, CI_JOB_TOKEN on GitLab, the CircleCI runner token. Make sure those credentials are present in the job environment. Supported platforms: Buildkite, CircleCI, GitHub Actions, GitLab.

CI integration examples

name: CI

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  build:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Build
        run: aspect build --task:name build //...

  test:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Test
        run: aspect test --task:name test --artifact-upload:upload-test-logs=failed //...

steps:
  - label: ":bazel: Build"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: aspect build --task:name build //...
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

  - label: ":bazel: Test"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: aspect test --task:name test --artifact-upload:upload-test-logs=failed //...
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

build:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  script:
    - aspect build --task:name build //...

test:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  script:
    - aspect test --task:name test --artifact-upload:upload-test-logs=failed //...
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

version: 2.1

orbs:
  setup-aspect: aspect-build/setup-aspect@2026.38.2

jobs:
  build:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Build
          command: aspect build --task:name build //...

  test:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Test
          command: aspect test --task:name test --artifact-upload:upload-test-logs=failed //...

workflows:
  ci:
    jobs:
      - build
      - test
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

​What changed

​Configuration

​Targets

​Bazel flags

​Test tag filters

​Code coverage

​Test log upload

​GitHub status checks

​Authentication

​Troubleshooting

​Artifact upload

​CI integration examples

What changed

Configuration

Targets

Bazel flags

Test tag filters

Code coverage

Test log upload

GitHub status checks

Authentication

Troubleshooting

Artifact upload

CI integration examples