Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

These guides are for Aspect Workflows customers moving from the legacy YAML-configured Rosetta task runner to the Aspect CLI’s built-in AXL tasks. If you’re not running Aspect Workflows today, head to the CLI overview — there’s nothing to migrate.
The Aspect CLI replaces the legacy Aspect Workflows task runner (“Rosetta”) and its YAML-configured .aspect/workflows/config.yaml. Each Rosetta task has a corresponding aspect <task> command that you invoke directly from your CI config — task logic now lives entirely inside the aspect invocation, so Aspect Workflows is no longer opinionated about how your CI is structured around it. Two wins follow:
  • Full CI flexibility. Task config sits in your CI YAML (or .aspect/config.axl) instead of a Rosetta-shaped wrapper. CI conditionals, retries, timeouts, and step ordering use your CI platform’s native primitives.
  • Same call locally. aspect <task> runs identically on a developer machine, so reproducing a CI failure is just running the command.

​
Per-task migration guides

Legacy Rosetta taskNew CLI commandMigration guide
build, testaspect build, aspect testaspect build / aspect test
delivery, delivery_manifestaspect deliveryaspect delivery
formataspect formataspect format
gazelle, configureaspect gazelleaspect gazelle
lintaspect lintaspect lint
warmingcoming soonwarming
checkoutnot in scopecheckout task
Each guide covers what changed, the configuration mapping (per-flag), and per-CI-host invocation examples (GitHub Actions, Buildkite, GitLab, CircleCI). Read it once for the task you’re migrating; the rest of this page is shared setup that applies to all of them.

​
checkout task

The legacy Rosetta checkout task ran a branch-freshness check after CI’s source checkout — fetching the target branch, computing the merge base, and posting a build annotation telling the developer how to rebase or merge when their branch was stale (update_strategy: rebase or merge). There’s no Aspect CLI equivalent and we don’t plan to add one. Source checkout (fetch depth, ref selection, submodules) is owned by your CI platform’s checkout action, and the rebase/merge behavior the legacy task provided is either built-in or trivially expressible in your CI YAML:
  • 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

Aspect CLI v2026.18.39 or newer, running on Aspect Workflows v5.17.19+ runners. Pin the CLI version in your repo’s .aspect/version.axl: 
version("2026.18.39") # or newer
The new tasks are AXL-powered and ship inside the CLI itself, so bumping version() pulls in newer task behavior independent of any Aspect Workflows runner upgrade. See version pinning for the full set of source options (local builds, custom registries, etc.).

​
Authentication

Features that post to GitHub (GithubStatusChecks, GithubLintComments) authenticate via the Aspect Workflows GitHub App. If your migration enables either, authenticate the CLI once before the first task migrates — it’s a per-repo setup, not per-task. ArtifactUpload, where used, authenticates against your CI platform’s native artifact API — see the per-task migration guide for setup. Aspect Workflows ships with Setup Aspect Workflows, an integration that generates the CI configuration and invokes Rosetta tasks for you. We recommend a two-step migration:
  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.
If you already invoke rosetta directly today, skip straight to step 2.
Stage the migration per-task rather than all at once. Each aspect <task> is independent — you can flip lint to aspect lint while leaving build, test, etc. on rosetta run. That way the blast radius of any per-task surprise is limited to one CI step.

​
Top-level workspaces

Skip this section unless your legacy .aspect/workflows/config.yaml had a top-level workspaces: list. Most repos don’t.
Rosetta’s top-level workspaces: list ran every task once per directory it named, supporting both single-workspace and multi-workspace repos. There is no equivalent in the Aspect CLI: aspect <task> runs from the current working directory, so the choice of workspace moves into your CI config. To run a task in a sub-directory, cd first; to cover multiple workspaces, declare a separate CI step per directory. Before — .aspect/workflows/config.yaml: 
workspaces:
  - .
  - mobile/ios
tasks:
  build:
  test:
  format:
After — write one CI step per workspace, cd-ing first. Example with aspect test on Buildkite: 
steps:
  - label: ":aspect: Test (root)"
    command: aspect test --task-key test-root //...

  - label: ":aspect: Test (mobile/ios)"
    command: |
      cd mobile/ios
      aspect test --task-key test-mobile-ios //...
The pattern generalizes to all five tasks and all four CI providers. A unique --task-key per workspace isn’t strictly required, but it’s recommended: features like GithubStatusChecks surface the task key in their output, so distinct keys make it easy to tell which run came from which workspace.

​
Where to next

Pick the migration guide for the task you’re starting with from the table at the top, or read in order — each guide is self-contained and can be done independently.

​
Migration support

As an Aspect Workflows customer, you have direct access to Aspect Support as part of your subscription — separate from the public community Slack open-source users land in. If you hit a snag during the migration, reach out:
  • 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.
We’re happy to pair-debug a stuck migration step, review your CI YAML before you flip a task over, or sanity-check a config.axl.