Overview

​

Why migrate

• New status checks. Dedicated per-task status checks surface results right on the commit — including a lint status check carrying the lint findings and a delivery status check carrying the delivery results. The aggregate PR/MR task-summary comment (GithubStatusComments / GitlabStatusComments) is substantially improved over the legacy comment.
• Clearer CLI output. Every task’s terminal output is improved, with clearly delineated phases for multi-phase tasks like lint and delivery and a timing summary at the end of each run.
• Faster selective delivery. Selective delivery’s change detection now uses an optimized, remote-cache-based hash check — it reads the action digest straight from the remote cache instead of downloading each target’s artifacts to hash them locally.
• Customize the product in AXL. AXL opens up extension points the YAML runner never had:
  • 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 actionable 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 structured per-target delivery manifest.
• Self-contained and portable. Each aspect <task> runs directly from your CI config — the Workflows Environment setup and Agent Health Check steps fold into the invocation, removing boilerplate from your CI YAML. Migrate one task at a time: flip lint to aspect lint while build and test stay on rosetta run, so the blast radius of any surprise is a single CI step.

​

Per-task guides

​

Migrating from Rosetta

​

Breaking changes

​

.aspect/workflows/bazelrc is not loaded by AXL tasks

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

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 rebases (or merges) before the rest of the build runs.

​

Requirements

version("2026.26.44") # 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 //...

​

Where to next

​

Migration support

• Your shared customer Slack channel — fastest path; the team is already in the loop on your environment.
• Email support@aspect.build — for issues you’d rather keep off Slack, or if a Slack channel isn’t set up yet.