CircleCI pipelines - Aspect Build

Your CircleCI pipeline runs on Aspect Workflows CI runners by targeting a runner group with resource_class:. 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 CircleCI is covered in .

Configure `.circleci/config.yml`

Point each job’s resource_class: at your Workflows resource class and keep your existing bazel steps. Every job runs the aspect-build/setup-aspect orb’s setup command after checkout. The setup step covers what it does and the parameters it takes. The when clause keeps the pipeline off scheduled triggers, which run the warming job instead.

.circleci/config.yml

version: 2.1

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

workflows:
  aspect-workflows:
    jobs:
      - build
      - test
    when:
      not:
        equal:
          - scheduled_pipeline
          - << pipeline.trigger_source >>

jobs:
  build:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    working_directory: /mnt/ephemeral/workdir
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Build
          command: bazel build //...

  test:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    working_directory: /mnt/ephemeral/workdir
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Test
          command: bazel test //...

Keep the setup-aspect/setup step on every job that runs bazel, so your calls pick up the runner’s cache and build event service.

Non-Bazel jobs

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

.circleci/config.yml

jobs:
  custom-job:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    working_directory: /mnt/ephemeral/workdir
    steps:
      - checkout
      - run: npm install && npm test

Aspect CLI tasks (optional)

Swap a bazel step 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. The CLI’s platform integrations (status checks, PR comments) authenticate with an ASPECT_API_TOKEN. Expose it as a CircleCI environment variable (via a context or project setting) so the setup step can authenticate the aspect <task> steps.

.circleci/config.yml

version: 2.1

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

parameters:
  force_targets:
    type: string
    default: ""

workflows:
  aspect-workflows:
    jobs:
      - build
      - test
      - format
      - lint
      - delivery:
          requires: [test]
          filters:
            branches:
              only: main
    when:
      not:
        equal:
          - scheduled_pipeline
          - << pipeline.trigger_source >>

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

  test:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    working_directory: /mnt/ephemeral/workdir
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Test
          command: aspect test --task:name test -- //...

  format:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    working_directory: /mnt/ephemeral/workdir
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Format
          command: aspect format --task:name format

  lint:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    working_directory: /mnt/ephemeral/workdir
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Lint
          command: aspect lint --task:name lint -- //...

  delivery:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    working_directory: /mnt/ephemeral/workdir
    environment:
      ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS: << pipeline.parameters.force_targets >>
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Delivery
          command: aspect delivery --task:name delivery --ci-host=circle --query='attr(tags, deliverable, //...)'

The delivery job runs only on main. --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). The force_targets pipeline parameter feeds ASPECT_WORKFLOWS_DELIVERY_FORCE_TARGETS, so a manually triggered pipeline can re-deliver named targets that delivery already resolved. See aspect delivery for --force-target. See Running tasks in CI for the full task reference and examples for all CI providers.

See Aspect Bazel Examples for a complete working example of a CircleCI config.

​Configure .circleci/config.yml

​Non-Bazel jobs

​Aspect CLI tasks (optional)

Configure `.circleci/config.yml`

Non-Bazel jobs

Aspect CLI tasks (optional)