Buildkite pipelines - Aspect Build

Your Buildkite pipeline runs on Aspect Workflows CI runners by targeting a runner group with agents: queue:. Your existing bazel steps keep working unchanged: the setup step wires the runner’s remote cache, build event service and NVMe-backed output base into every invocation.

Registering the runners with Buildkite is covered in .

Configure a pipeline

Create a new pipeline for your Workflows build, or choose an existing one and configure it.
- If you use GitHub, follow these steps to integrate your repository with Buildkite.
Choose a queue for the pipeline upload step:
- If you have access to Buildkite hosted agents, create an agent queue with a small agent (2 vCPU and 4 GB RAM is enough) to run it.
- Otherwise, target an Aspect Workflows runner group such as aspect-default.
In the Buildkite interface, access Steps > Convert to YAML Steps and paste the upload step. This one targets a hosted agent queue named bk-small:

steps:
  - label: ":aspect: Upload .buildkite/pipeline.yaml"
    agents:
      queue: bk-small
    command: buildkite-agent pipeline upload .buildkite/pipeline.yaml

This uploads the Buildkite pipeline defined in .buildkite/pipeline.yaml in your repository.

Define your Buildkite pipeline. Point each step’s command at your existing bazel invocation and target your Workflows runner queue.

Each step uses the aspect-build/setup-aspect Buildkite plugin. The setup step covers what it does and the inputs it takes.

.buildkite/pipeline.yaml

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

  - key: test
    label: ":bazel: Test"
    command: bazel test //...
    agents:
      queue: aspect-default
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2

See Aspect Bazel Examples for a complete working example of a Buildkite pipeline.

Non-Bazel jobs

Jobs that don’t call Bazel need no setup step. Target the runner group and run your commands:

.buildkite/pipeline.yaml

steps:
  - label: "Custom job"
    command: npm install && npm test
    agents:
      queue: aspect-default

Aspect CLI tasks (optional)

Swap a bazel command for the matching aspect <task> from the open-source Aspect CLI to add status checks, inline PR comments with one-click suggested fixes, retries on transient Bazel errors and selective delivery. Using the Aspect CLI’s platform integrations requires an ASPECT_API_TOKEN. Store it as a Buildkite secret and name it in the secrets: of each step that calls aspect <task>, so the setup plugin can exchange it for a session before the step runs.

.buildkite/pipeline.yaml

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

  - key: test
    label: ":bazel: Test"
    command: aspect test --task:name test -- //...
    secrets: [ASPECT_API_TOKEN]
    agents:
      queue: aspect-default
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2

  - key: format
    label: ":hammer_and_wrench: Format"
    command: aspect format --task:name format
    secrets: [ASPECT_API_TOKEN]
    agents:
      queue: aspect-default
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2

  - key: lint
    label: ":lint-roller: Lint"
    command: aspect lint --task:name lint -- //...
    secrets: [ASPECT_API_TOKEN]
    agents:
      queue: aspect-default
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2

  - key: delivery
    label: ":package: Delivery"
    depends_on: [test]
    if: build.branch == pipeline.default_branch
    command: aspect delivery --task:name delivery --query='attr(tags, deliverable, //...)'
    secrets: [ASPECT_API_TOKEN]
    agents:
      queue: aspect-default
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2

The delivery step runs only on the default branch. --query selects the targets to deliver; without it or positional targets, aspect delivery delivers nothing. You can set the query once in .aspect/config.axl instead (ctx.tasks["delivery"].args.query). See aspect delivery. See Running tasks in CI for the full task reference and examples for all CI providers.

​Configure a pipeline

​Non-Bazel jobs

​Aspect CLI tasks (optional)

Configure a pipeline

Non-Bazel jobs

Aspect CLI tasks (optional)