Migrating from YAML tasks

​

What’s changing

​

What else you get

• New status checks. Per-task status checks on the commit, including a lint status check with the lint findings and a delivery status check with the delivery results. The PR/MR task-summary comment (GithubStatusComments / GitlabStatusComments) replaces the legacy comment.
• Clearer CLI output. Named phases for multi-phase tasks like lint and delivery, and a timing summary at the end of each run.
• Faster selective delivery. Change detection reads each target’s action digest from the remote cache instead of downloading its artifacts to hash them locally.
• Extension points in AXL:
  • Custom tasks: define your own aspect <task> commands alongside the built-ins.
  • Listen for build events: subscribe your AXL code to Bazel’s Build Event Stream and act on events as they arrive.
  • Customizable tips: surface your own tips in the terminal, status checks, and PR comments.
  • Customizable repro & fix suggestions: accept, reject, or rewrite the repro/fix commands tasks emit (e.g. point them at your team’s wrapper).
  • Customizable delivery manifest: enrich, render, and act on the per-target delivery manifest.
• Less CI YAML. The Workflows Environment setup and Agent Health Check steps fold into each aspect <task> invocation.

​

What the migration looks like

• It’s repository-side. In most cases no infrastructure changes are needed, only configuration files in your repo.
• It goes one task at a time. Flip lint to aspect lint while build and test stay on rosetta run. Many teams start with gazelle or delivery (see the recommended migration path).
• It’s testable first. Run the new task as a non-blocking step and compare it with your current setup before switching over.
• An AI coding assistant can do most of it. Point one at these migration docs and let it make the bulk of the changes.

​

Per-task guides

​

Breaking changes

​

.aspect/workflows/bazelrc isn’t loaded by AXL tasks

# flags only active when --config=ci is passed
build:ci --remote_download_minimal

# flags a task's sidecar query also needs: `build:ci` does not reach `bazel query`
common:ci --keep_going

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

def config(ctx: ConfigContext):
    is_ci = bool(ctx.std.env.var("CI"))
    if is_ci:
        ctx.traits[BazelTrait].extra_flags.extend([
            "--config=ci",
        ])

​

checkout task

• GitHub Actions: actions/checkout@v6 already checks out the synthetic merge ref for PR events (refs/pull/<n>/merge), which is the PR head pre-rebased onto the target. update_strategy: rebase was a no-op here.
• Other CI hosts (Buildkite, GitLab, CircleCI): customize your checkout step to fetch the target branch and rebase (or merge) before the rest of the build runs.

​

Requirements

version("2026.41.50") # or newer

​

Authentication

​

Recommended migration path

1. Eject from Setup Aspect Workflows. Invoke rosetta run <task> directly from your own CI config. Task behavior is identical to what the generated config did, so this step decouples the “where CI lives” change from the “what CI runs” change and de-risks the migration.
2. Swap rosetta for aspect. Replace each rosetta run <task> call with the corresponding aspect <task> command. Per-task migration guides above cover the flag mapping. While you’re there, you can also drop the boilerplate that previously wrapped each rosetta run <task> call: the Workflows Environment setup and Agent Health Check steps are now self-contained inside the aspect <task> invocation and no longer need to be declared in your CI config.

​

Top-level workspaces

workspaces:
  - .
  - mobile/ios
tasks:
  build:
  test:
  format:

steps:
  - label: ":aspect: Test (root)"
    command: aspect test --task:name test-root //...

  - label: ":aspect: Test (mobile/ios)"
    command: |
      cd mobile/ios
      aspect test --task:name test-mobile-ios //...

​

Migration support