aspect gazelle - Aspect Build

Rosetta’s gazelle task (Workflows 5.x) ran a bazel-gazelle .check target against the repo and annotated the build with the produced diff if BUILD files were out of date. aspect gazelle replaces it, and also subsumes the older configure task (see below). aspect gazelle builds your gazelle target and runs it once with -mode=diff to capture the unified diff that gazelle would produce. From there:

Apply mode (default off CI): the captured diff is applied to your working tree via git apply -p0.
Check mode (--check-only=true, default on CI): the diff is reported without modifying the tree.

--check-only defaults to auto, which picks check mode on a recognized CI host and apply mode elsewhere. A non-empty diff is a “BUILD files out of date” verdict, and --severity decides what that verdict does: its default, auto, fails the task on CI and reports it as info off CI.

Two legacy tasks, one new task

Rosetta had two different YAML tasks that both produced “BUILD files are out of date” verdicts:

gazelle: ran a user-defined gazelle.check target (default //:gazelle.check) and looked at its exit code + stderr.
configure: ran the legacy aspect-cli’s built-in bazel configure command, which embedded a prebuilt gazelle binary inside the CLI itself. No //tools/gazelle target was required because the binary shipped with the CLI.

Both migrate to aspect gazelle. The new task needs a //tools/gazelle:gazelle target wired to aspect_gazelle_prebuilt; see Setup.

Setup

Add aspect_gazelle_prebuilt to MODULE.bazel and define a gazelle target. We recommend the prebuilt binary (no Go toolchain required); see the aspect-gazelle release notes for the latest version.

# MODULE.bazel
bazel_dep(name = "aspect_gazelle_prebuilt", version = "0.0.26")

# tools/gazelle/BUILD
load("@aspect_gazelle_prebuilt//:def.bzl", "aspect_gazelle")

aspect_gazelle(
    name = "gazelle",
    languages = ["go", "proto", "python"],  # whichever fit your repo
)

If you’d rather build gazelle from source (upstream bazel-contrib/bazel-gazelle macro + a Go toolchain), aspect gazelle works against that too.

What changed

Area	YAML-configured tasks	Aspect CLI tasks
Invocation	`rosetta run gazelle` · `rosetta run configure` (which called `bazel configure` internally)	`aspect gazelle`
Gazelle binary	`gazelle`: user-supplied target (default `//:gazelle.check`) · `configure`: built into the legacy aspect-cli	User-supplied target (default `//tools/gazelle:gazelle`)
Target	`gazelle`: `target:` (default `//:gazelle.check`) · `configure`: n/a (used the bundled binary)	`--gazelle-target` (default `//tools/gazelle:gazelle`)
Mode	Both always `-mode diff` (`gazelle.check` ran gazelle that way; `bazel configure` passed `--mode=diff`)	Applies via `git apply -p0` off CI; check-only on CI (`--check-only`, default `auto`)
Gazelle subcommand	Always the default (no explicit subcommand)	`--gazelle-command=fix\|update` (default: none, so gazelle’s own default applies)
Extra gazelle flags	None (no passthrough)	`--gazelle-flag=<flag>` (repeatable), forwarded to the gazelle binary
Directory scope	Whole repo	Positional args after flags: `aspect gazelle tools/go services/api`. Gazelle only walks those subtrees
Detection	`gazelle`: exit code from the gazelle binary; non-zero meant BUILDs out of date · `configure`: special `CONFIGURE_DIFF` exit code	Captured `-mode=diff` stdout: non-empty diff = BUILDs out of date
Apply path	Both out-of-band: user runs `bazel run //:gazelle` (or `bazel configure` for the `configure` task) after the failed CI step, then commits	In-band off CI: `git apply -p0 <captured-diff>` updates the working tree as part of the `aspect gazelle` invocation. On CI, check mode mirrors the legacy diff-only behavior
Gazelle invocations per task run	One (the gazelle binary itself)	One. The apply step uses `git apply`, not a second gazelle invocation, which avoids re-running gazelle’s slow whole-repo scan
Diff archival	Both: annotated with the (truncated) task output	`--upload-gazelle-diff` (on by default) uploads the patch as a `gazelle.patch` CI artifact via the same uploader build/test/format use
Workspaces	`workspaces:` top-level list ran each task once per directory	`cd <dir>` in your CI config; run `aspect gazelle` from there. To cover multiple workspaces, declare a separate CI step per directory.

Configuration

Most settings below can be applied either way:

CLI flag: pass the flag at invocation time (e.g. aspect gazelle --check-only=true). Good for overrides on individual task invocations, or experimenting with a setting before committing it.
.aspect/config.axl: declare it once in your repo’s AXL config so every aspect gazelle invocation picks it up. Good for settings that should apply to all invocations of a task type.

Pick whichever fits; you only need one. Where both work, the sections below show them side-by-side under After.

Scope and change detection

Nothing in Rosetta corresponds to these; they are how aspect gazelle keeps a CI run proportional to the change. aspect gazelle --scope=changed is the headline CI behavior.

Flag	Default	What it does
`--scope`	`all`	`all` updates the whole repo; `changed` limits the run to the directories of changed files
`--base-ref`	(from CI)	The ref to diff against. Falls back to the CI environment, then the remote’s default branch, then `origin/main`
`--merge-base`	(empty)	Diff against this commit instead of resolving a base
`--scope-all-on-change`	`["BUILD.bazel", "MODULE.bazel"]`	Changes to these escalate to a whole-repo run. Setting it replaces the defaults
`--changed-file-pattern`	(empty)	Narrows which changed files count — for example to the languages your plugins cover

See change detection for how a base is resolved and what happens when it can’t be.

Gazelle target

Before: .aspect/workflows/config.yaml:

tasks:
  gazelle:
    target: //:gazelle.check

After: CLI flag or config.axl:

aspect gazelle --gazelle-target=//tools/gazelle:gazelle

def config(ctx: ConfigContext):
    ctx.tasks["gazelle"].args.gazelle_target = "//tools/gazelle:gazelle"

The default gazelle target moved from //:gazelle.check to //tools/gazelle:gazelle:

Out of the root package. Defining gazelle() at //tools/gazelle instead of //:gazelle.check keeps the gazelle load(…) out of your root BUILD.bazel, so commands that touch the root package don’t fetch and analyze gazelle-only machinery.
No more .check suffix. The task drives gazelle in -mode=diff at runtime via a flag override, so a single target works for both apply and check semantics.

If you relied on the legacy default and your gazelle.check target lives at the root, point —gazelle-target at the apply target (//:gazelle, not //:gazelle.check). Or migrate the BUILD file to tools/gazelle/BUILD to match the new default (see Setup).

Migrating from the `configure` task

If your repo previously had:

tasks:
  configure:

and relied on the legacy aspect-cli’s built-in gazelle, the migration is to add an aspect_gazelle target backed by aspect_gazelle_prebuilt at //tools/gazelle:gazelle (see Setup) and switch to aspect gazelle. aspect_gazelle_prebuilt fetches a prebuilt gazelle binary, so you keep configure’s “no Go toolchain, no build-from-source” benefit. Once that’s wired up, aspect gazelle on CI is the direct replacement for rosetta run configure.

# Before
tasks:
  configure:

# After (CI YAML; see Examples below for the full per-host shape):
- aspect gazelle

Mode: apply vs. check

Before: both legacy tasks always ran in diff-only mode. The user fixed any reported issues by re-running bazel run :gazelle (for the gazelle task) or bazel configure (for configure). After: off CI the task applies the diff for you; on CI it matches the legacy diff-only behavior and fails when anything would change:

aspect gazelle                                     # off CI: apply changes via `git apply -p0`
aspect gazelle --check-only=true --severity=fail   # don't modify the tree; exit 1 if anything would change

Why the default differs by host: locally, aspect gazelle and “update my BUILDs” are usually the same intent. CI inverts that, so check mode is the default there.

Gazelle subcommand (`fix` vs `update`)

The legacy tasks always ran gazelle without an explicit subcommand (defaulting to update / fix depending on the language plugin). aspect gazelle exposes this as --gazelle-command:

aspect gazelle                          # no subcommand (gazelle's default)
aspect gazelle --gazelle-command=update # explicitly run 'update'
aspect gazelle --gazelle-command=fix    # 'fix': also removes obsolete rules

Most repos can leave this unset. Use --gazelle-command=fix when you want gazelle to clean up deleted files or apply language-specific migrations on top of normal rule generation. update-repos isn’t supported here. Run it directly with bazel run //tools/gazelle:gazelle -- update-repos when you need to update Go repository rules.

Passing arbitrary gazelle flags (`--gazelle-flag`)

--gazelle-flag passes extra flags directly to the gazelle binary (repeatable):

aspect gazelle --gazelle-flag=-progress --gazelle-flag=-r tools/go

def config(ctx: ConfigContext):
    ctx.tasks["gazelle"].args.gazelle_flags = ["-progress", "-r"]

This is useful for:

-progress: print progress output (aspect-gazelle prebuilt only).
-cache: enable gazelle’s build cache (aspect-gazelle prebuilt only).
-r: recurse into subdirectories.
Any other upstream gazelle flag not yet exposed as a first-class task arg.

Note: flags specific to aspect_gazelle_prebuilt (like -progress and -cache) will cause errors if you’re using a from-source gazelle target that doesn’t recognize them. Don’t set those in config.axl if your target may vary. Any -mode/--mode flag passed via --gazelle-flag is ignored; the task controls the mode.

Limiting scope with directories

Pass directories as positional arguments after all flags. Gazelle limits its walk to those subtrees:

# Walk only tools/go and services/api
aspect gazelle tools/go services/api

# CI check limited to a subtree
aspect gazelle --check-only=true services/payments

In .aspect/config.axl, set dirs as a list:

def config(ctx: ConfigContext):
    ctx.tasks["gazelle"].args.dirs = ["tools/go", "services/api"]

When no directories are specified (the default), gazelle walks the entire repo from the workspace root, matching the legacy behavior.

Diff archival

Before: the legacy tasks attached the diff to a CI annotation (truncated to ~20 lines, with the rest in the terminal-detail block). After: on by default. When BUILD files are out of date on CI, the task uploads the diff as a gazelle.patch artifact via the same uploader build/test use for test logs, on GitHub Actions, Buildkite, CircleCI, and GitLab. To turn it off:

aspect gazelle --upload-gazelle-diff=false

def config(ctx: ConfigContext):
    ctx.tasks["gazelle"].args.upload_gazelle_diff = False

Examples

Standard gazelle check on PRs

Before: .aspect/workflows/config.yaml:

tasks:
  gazelle:
    target: //:gazelle.check

After: CI configuration:

on:
  pull_request:
    branches: [main]

jobs:
  gazelle:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      contents: read    # actions/checkout
      id-token: write   # artifact uploads and the PR summary comment
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - name: Gazelle
        run: aspect gazelle --task:name gazelle

steps:
  - label: ":deer: Gazelle"
    plugins:
      - aspect-build/setup-aspect#8de9aed254d0699baf201f66e2076fc8c09f42b9: ~ # v2026.38.2
    command: aspect gazelle --task:name gazelle
    secrets:
      - ASPECT_API_TOKEN
    agents:
      queue: aspect-default

include:
  - component: $CI_SERVER_FQDN/aspect-build/setup-aspect-gitlab-component/setup@2026.38.3

gazelle:
  extends: .setup-aspect
  tags:
    - aspect-workflows
    - aspect-default
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - aspect gazelle --task:name gazelle
# Set ASPECT_API_TOKEN as a masked CI/CD variable in Settings → CI/CD → Variables.

version: 2.1

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

jobs:
  gazelle:
    machine: true
    resource_class: YOUR-ORG/aspect-default
    steps:
      - checkout
      - setup-aspect/setup
      - run:
          name: Gazelle
          command: aspect gazelle --task:name gazelle

workflows:
  ci:
    jobs:
      - gazelle
# Set ASPECT_API_TOKEN as a project environment variable or context secret.

​Two legacy tasks, one new task

​Setup

​What changed

​Configuration

​Scope and change detection

​Gazelle target

​Migrating from the configure task

​Mode: apply vs. check

​Gazelle subcommand (fix vs update)

​Passing arbitrary gazelle flags (--gazelle-flag)

​Limiting scope with directories

​Diff archival

​Examples

​Standard gazelle check on PRs