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.

This is the per-task migration guide for the legacy Rosetta buildifier task. See Migrating from legacy YAML-configured tasks for shared setup (CLI version pinning, the recommended two-step migration path, top-level workspaces:).
The legacy Rosetta buildifier task ran a Bazel target (defaulting to //:buildifier.check) that invoked buildifier in check mode against the workspace’s Starlark files, surfacing lint warnings and formatting diffs as CI annotations. There is no aspect buildifier command and we don’t plan to add one. aspect format already runs buildifier as one of its formatters via format_multirun — set the starlark attribute on your formatter target to a buildifier binary, and aspect format picks up .bzl, BUILD, BUILD.bazel, and MODULE.bazel automatically. If you want buildifier to run as its own dedicated CI step (separate from the rest of aspect format), declare a Starlark-only format_multirun target and point a separate aspect format invocation at it via --formatter-target. See Running buildifier as a dedicated task below.

​
What changed

AreaYAML-configured tasksAspect CLI tasks
Invocationrosetta run buildifieraspect format (Starlark files included alongside other formatters)
Check targettarget: (default //:buildifier.check)--formatter-target (default //tools/format:format) — points at a format_multirun whose starlark = attribute is set
Fix targetfix_target: (default //:buildifier)--formatter-target runs the fix target by default; the legacy “check then suggest fix” annotation is replaced by aspect format’s pre/post-snapshot diff flow
Lint warningsSurfaced as a separate annotation pointing at buildtools/WARNINGS.mdNot surfaced separately — buildifier’s -mode=fix (the default in format_multirun) applies what it can fix; remaining lint warnings appear in aspect format’s output and the unified format check-run
Diff archivalReused the legacy format task’s diff handling when invoked via bazel runaspect format --upload-format-diff archives the patch as format.patch via ArtifactsTrait. See aspect format → Diff archival
Soft-failsoft_fail: true downgraded the failure to a warningaspect format --soft-fail. See aspect format → Soft-fail
Ignore patternsn/a--ignore-pattern (repeatable). See aspect format → Ignore patterns
The detection mechanism, scope handling, soft-fail semantics, ignore-pattern syntax, and CI artifact upload behavior all come from aspect format. Read the aspect format migration guide for the full surface — this page only covers what is buildifier-specific.

​
Wiring buildifier into your formatter target

The new default formatter target is //tools/format:format. Add starlark = to its format_multirun invocation, pointing at a buildifier binary. Most repos already have one available via the buildifier_prebuilt module: MODULE.bazel: 
bazel_dep(name = "buildifier_prebuilt", version = "8.2.0.2")  # or newer
tools/format/BUILD.bazel: 
load("@aspect_rules_lint//format:defs.bzl", "format_multirun")

format_multirun(
    name = "format",
    starlark = "@buildifier_prebuilt//:buildifier",
    # ...other languages your repo formats:
    # rust = "@rules_rust//tools/upstream_wrapper:rustfmt",
    # go = "@aspect_rules_lint//format:gofumpt",
    # javascript = ":prettier",
)
That’s the whole switch in the common case — aspect format will now run buildifier on Starlark files as part of its normal flow. No new task wiring, no new CI step required.
The legacy task’s target and fix_target (//:buildifier.check / //:buildifier) are no longer used. format_multirun produces both the fix target (//tools/format:format) and a check-only sibling (//tools/format:format.check) automatically; aspect format invokes the fix target and decides pass/fail by diffing the working tree before and after. You can delete the old labels once nothing references them.

​
Running buildifier as a dedicated task

Some repos want buildifier on its own CI step — a fast Starlark-only check that runs in parallel with (and finishes well before) the bigger language formatters. The legacy buildifier task gave that for free. The new pattern: declare a second format_multirun target that only sets starlark =, then point a dedicated aspect format invocation at it via --formatter-target. The default formatter target in tools/format:format keeps every other language; the Starlark-only target lives alongside it. tools/format/BUILD.bazel: 
load("@aspect_rules_lint//format:defs.bzl", "format_multirun")

format_multirun(
    name = "format",
    starlark = "@buildifier_prebuilt//:buildifier",
    # ...other languages...
)

format_multirun(
    name = "format-starlark",
    starlark = "@buildifier_prebuilt//:buildifier",
)
Then in your CI, run two aspect format steps in parallel — one for buildifier and one for everything else. Use --task-key to give each a distinct status check name, and --ignore-pattern to keep them from doing duplicate work: 
jobs:
  buildifier:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      id-token: write
    env:
      ASPECT_API_TOKEN: ${{ secrets.ASPECT_API_TOKEN }}
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }
      - name: Buildifier
        run: |
          aspect format \
            --task-key buildifier \
            --formatter-target=//tools/format:format-starlark

  format:
    runs-on: [self-hosted, aspect-workflows, aspect-default]
    permissions:
      id-token: write
    env:
      ASPECT_API_TOKEN: ${{ secrets.ASPECT_API_TOKEN }}
    steps:
      - uses: actions/checkout@v6
        with: { fetch-depth: 0 }
      - name: Format (non-Starlark)
        run: |
          aspect format \
            --task-key format \
            --ignore-pattern='**/*.bzl' \
            --ignore-pattern='**/BUILD' \
            --ignore-pattern='**/BUILD.bazel' \
            --ignore-pattern='**/MODULE.bazel' \
            --ignore-pattern='**/WORKSPACE' \
            --ignore-pattern='**/WORKSPACE.bazel'
The same split generalizes — declare one format_multirun per group of formatters you want as a separate CI step (e.g. one for Starlark, one for JavaScript/TypeScript/CSS via Prettier, one for everything else), and use --ignore-pattern on the catch-all step to avoid re-formatting files the dedicated step already handled.
Pinning --formatter-target for a dedicated buildifier step at the CLI flag level — rather than in .aspect/config.axl — is intentional. config.axl is global to all aspect format invocations, so setting formatter_target there would also redirect your default aspect format (the one developers run locally). Per-CI-step overrides belong on the CLI.

​
Lint warnings: use aspect lint

The legacy task surfaced buildifier’s lint warnings (the --lint=warn output that lists rule violations like module-docstring, name-conventions, etc.) as a dedicated annotation pointing at buildtools/WARNINGS.md. In the new world, that lives in aspect lint, not aspect format. format_multirun runs buildifier in fix mode and auto-applies what it can; warnings buildifier won’t auto-fix don’t surface as a status check from aspect format. To gate on those warnings, wire buildifier in as a rules_lint lint aspect and run it from aspect lint. tools/lint/linters.bzl: 
load("@aspect_rules_lint//lint:buildifier.bzl", "lint_buildifier_aspect")

buildifier = lint_buildifier_aspect(
    binary = Label("@buildifier_prebuilt//:buildifier"),
    # warnings = "all",  # default; or pass a comma-separated allowlist
)
By default the aspect visits bzl_library targets. To lint BUILD.bazel, MODULE.bazel, or other Starlark files, add tags = ["starlark"] (or tags = ["lint-with-buildifier"]) to a target listing them in srcs: 
filegroup(
    name = "starlark_files",
    srcs = ["BUILD.bazel", "MODULE.bazel", "defs.star"],
    tags = ["starlark"],
)
Then add //tools/lint:linters.bzl%buildifier to your aspect lint invocation — either as --aspect on the CLI or in .aspect/config.axl. See the aspect lint migration guide for the wiring details. Output is SARIF, deduplicated and (on GitHub Actions, by default) posted as PR comments by the GithubLintComments feature. Recommended split:
ConcernTaskMode
Auto-applied formatting + simple fixesaspect format (Starlark via format_multirun)--lint=fix (in-place edits)
Warnings that need human attentionaspect lint --aspect=…%buildifier--lint=warn (SARIF + PR comments)
This is the same split rules_lint uses for every other Starlark-aware tool — formatting in format_multirun, diagnostics in the lint aspect — so the buildifier wiring matches the rest of your linters.

​
Examples

​
Buildifier folded into the default aspect format step

The simplest migration — Starlark gets formatted alongside everything else, no separate CI step: Before — .aspect/workflows/config.yaml: 
tasks:
  buildifier:
    target: //:buildifier.check
    fix_target: //:buildifier
  format:
    target: //tools/format:format
    format_changed: true
After — tools/format/BUILD.bazel: 
format_multirun(
    name = "format",
    starlark = "@buildifier_prebuilt//:buildifier",
    # ...other languages...
)
CI configuration: just the standard aspect format step from the aspect format migration guide. No new step is needed; buildifier runs as part of it.

​
Buildifier as a dedicated parallel CI step

Use the Running buildifier as a dedicated task snippets above.