aspect buildifier - Aspect Build

aspect buildifier formats Starlark files (BUILD, BUILD.bazel, MODULE.bazel, .bzl, .axl, WORKSPACE and more) using the buildifier binary from buildifier_prebuilt. It’s registered as an alias of aspect format with format.alias() in .aspect/config.axl. That makes it a CLI command with no BUILD target or rules_lint dependency: a bazel_dep on buildifier_prebuilt and a few lines of AXL. aspect buildifier runs through aspect format: the same change detection, the same drift check, the same --severity behavior and the same artifact upload. Only the formatter binary and the file patterns differ.

Setup

MODULE.bazel:

bazel_dep(name = "buildifier_prebuilt", version = "10.1.0")

.aspect/config.axl:

load("@aspect//format.axl", "format")

buildifier = format.alias(
    defaults = {
        "formatter_target": "@buildifier_prebuilt//buildifier",
        # buildifier_binary is a symlink to the raw Go binary; it does not
        # switch to $BUILD_WORKING_DIRECTORY on its own, so we run it in
        # the user's cwd to make relative paths resolve.
        "run_in": "cwd",
        # Fires only when the format task would otherwise pass zero files
        # to the formatter (e.g. `--scope=all`, or a `--scope=changed` run
        # that degraded because no changed files matched). The bare
        # buildifier binary needs `-r .` to walk the tree on its own. Inert
        # whenever a file list is passed, so `--scope=changed` (the default)
        # and per-file invocations are unaffected.
        "formatter_args_for_tree_walk": ["-r", "."],
        "include_patterns": [
            "**/BUILD",
            "**/BUILD.bazel",
            "**/MODULE.bazel",
            "**/*.MODULE.bazel",
            "**/WORKSPACE",
            "**/WORKSPACE.bazel",
            "**/*.axl",
            "**/*.bzl",
        ],
    },
    summary = "Format Starlark files using buildifier.",
)

def config(ctx: ConfigContext):
    ctx.tasks.add(buildifier)

This registers aspect buildifier as a real CLI command. Run it locally:

aspect buildifier              # format changed Starlark files (default)
aspect buildifier --scope=all  # walk the tree and format every Starlark file
aspect buildifier BUILD.bazel  # format specific files explicitly

—scope=all covers a narrower file set than —scope=changed. In —scope=all the format task hands off discovery to buildifier’s -r . tree walk, which has a hard-coded list of recognized file types: BUILD, BUILD.bazel, MODULE.bazel, WORKSPACE, WORKSPACE.bazel, *.bzl, *.star. Files matching the alias’s include_patterns but not on buildifier’s list, notably *.axl, *.MODULE.bazel, Tiltfile and BUCK, are skipped. include_patterns filters the changed-file list in —scope=changed and the post-format diff in both modes, but it doesn’t extend buildifier’s tree walk.In —scope=changed (the default) the task passes the changed file list to buildifier positionally, so every extension in include_patterns is formatted. The same applies when you pass files explicitly (aspect buildifier path/to/file.axl).For a CI job that needs an extension buildifier doesn’t discover, prefer —scope=changed against a broader base ref, or invoke buildifier on the file set yourself.

Configuration

All aspect format configuration applies: --scope, --severity, --include-pattern, --exclude-pattern, --upload-format-diff. The format.alias() defaults set the formatter target and file patterns so you don’t repeat them on every invocation. To add or remove file patterns, keep run_in and formatter_args_for_tree_walk and change include_patterns:

.aspect/config.axl

buildifier = format.alias(
    defaults = {
        "formatter_target": "@buildifier_prebuilt//buildifier",
        "run_in": "cwd",
        "formatter_args_for_tree_walk": ["-r", "."],
        "include_patterns": [
            "**/BUILD",
            "**/BUILD.bazel",
            "**/*.bzl",
            # omit .axl if you don't use that extension
        ],
    },
    summary = "Format Starlark files using buildifier.",
)

CI example

.github/workflows/buildifier.yaml

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read    # actions/checkout
  id-token: write   # artifact uploads and the PR summary comment

jobs:
  buildifier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: aspect-build/setup-aspect@ebca96eb49ef58c00d4226de8bd3a0813507dd87 # v2026.38.3
        with:
          aspect-api-token: ${{ secrets.ASPECT_API_TOKEN }}
      - run: aspect buildifier --task:name buildifier

The --task:name matches the alias name you registered. Complete pipeline examples shows the same setup on Buildkite, GitLab CI and CircleCI, and on Aspect Workflows CI runners.

​Setup

​Configuration

​CI example

Setup

Configuration

CI example