Warming - Aspect Build

aspect ci warming requires Aspect CLI v2026.39.10 or newer (pinned via .aspect/version.axl). For the legacy rosetta run warming task, see ; to move over, follow the migration guide.

How warming works

Aspect Workflows CI runners are persistent: a runner reuses its caches across the jobs it serves. When a runner group scales up, a new runner starts cold, and its first job has to fetch every external repository and run each repository rule before Bazel can analyze anything. Warming front-loads that work:

A scheduled warming job, typically on main, runs aspect ci warming. The task runs the runner health check, clears the previous Bazel state on the runner’s storage mount, and runs bazel build --nobuild on the target patterns. That fetches external repositories, runs repository rules, and loads and analyzes the targets; no build actions execute. The task then uploads the repository cache, output base, and Bazel caches as the archive for the runner group’s warming set.
A new runner restores the latest archive for its warming set while it boots. The first job’s health check waits for the restore to finish before Bazel starts. To hold the CI agent until the restore finishes instead, set wait_for_warming, or ask Aspect to on a deployment hosted by Aspect (off by default; see ).
That first bazel build or bazel test starts with external repositories fetched and repository rules run.

Warming doesn’t populate the remote cache: build outputs still come from the remote cache or are built by the job. An archive restores only on runners booted from the same machine image it was created on, so after a runner image upgrade, new runners boot cold until the next warming job runs. The archive also carries the Aspect CLI’s download caches, so a warm runner doesn’t re-fetch the CLI.

Turning it on

Warming is enabled per runner group, and each group that needs different caches gets its own warming set: one for a group that also restores a pnpm store or Poetry environments, another for a group on a different CPU architecture. On a deployment hosted by Aspect, ask for the groups you want warmed. On a self-hosted deployment, set warming = true on the group in Terraform; see .

Configure the warming job

Add a scheduled job that runs aspect ci warming on the runner group you want warm, against your main branch, once or twice a day. Each warming set needs its own job, on a runner group that uses that set. With no target patterns, the task warms ..., every target in the package at and beneath the current directory. The examples pass //... explicitly, and schedule the job daily at 12:00 UTC (0 12 * * *); adjust the time to your team’s working hours. For the full set of flags and target options, see aspect ci warming.

The warming task doesn’t need the setup-aspect step: it runs on an Aspect Workflows CI runner, where aspect is already on the PATH. The GitHub Actions example still uses the action because it provides the auth aspect needs to post its status check; on other providers, supply ASPECT_API_TOKEN instead (see the comments in the examples).

GitHub Actions
Buildkite
GitLab CI
CircleCI

.github/workflows/aspect-workflows-warming.yaml

name: Aspect Workflows Warming

on:
  schedule:
    - cron: '0 12 * * *'
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

jobs:
  warming:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - run: aspect ci warming --task:name warming -- //...

warming-pipeline.yaml

# ASPECT_API_TOKEN is a Buildkite secret.
steps:
  - label: ":fire: Warming"
    agents:
      queue: aspect-default
    command: aspect ci warming --task:name warming -- //...
    secrets: [ASPECT_API_TOKEN]

Create a new Buildkite pipeline with these steps, then open its Pipeline Settings > Schedules > New Schedule and set the cron interval to 0 12 * * *.

.gitlab-ci.yml

# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings > CI/CD > Variables.
stages:
  - CI

warming:
  tags: [aspect-workflows, aspect-default]
  stage: CI
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
  script:
    - aspect ci warming --task:name warming -- //...

If your .gitlab-ci.yml has workflow: rules, they must let scheduled pipelines through, or the schedule creates no pipeline. Keep your other jobs off the schedule with their own rules, as the GitLab CI/CD pipelines example does.To schedule it, open Build > Pipeline schedules > New schedule in your project:

Set the description to Aspect Workflows Warming.
Set Interval pattern to 0 12 * * * with Cron timezone set to UTC.
Under Select target branch or tag, pick the branch to warm from.
Check Activated and click Create pipeline schedule.

.circleci/config.yml

# Set ASPECT_API_TOKEN as a project environment variable or context secret.
workflows:
  aspect-workflows-warming:
    jobs:
      - warming
    when:
      and:
        - equal:
          - scheduled_pipeline
          - << pipeline.trigger_source >>
        - equal:
          - aspect-workflows-warming
          - << pipeline.schedule.name >>

jobs:
  warming:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    working_directory: /mnt/ephemeral/workdir
    steps:
      - checkout
      - run:
          name: Warming
          command: aspect ci warming --task:name warming -- //...

Add a scheduled trigger in CircleCI (Project Settings > Triggers) named aspect-workflows-warming, with the cron schedule 0 12 * * *. Guard your other workflows with when: not: equal: [scheduled_pipeline, << pipeline.trigger_source >>] so the schedule runs only the warming job, as the CircleCI pipelines example does.

​How warming works

​Turning it on

​Configure the warming job

How warming works

Turning it on

Configure the warming job