# Add a Buildifier Check to CI for a Bazel Repository

Yes. An agent runs buildifier over your BUILD and .bzl files, fixes the formatting it finds, and adds a CI step that fails on unformatted or lint-warned Starlark.

[Run this on Rush](https://cloud.getrush.ai/run/add-buildifier-to-ci/bazel/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts by finding how Starlark is checked today. In a repository like bazelbuild/examples there is a `.pre-commit-config.yaml` that runs `keith/pre-commit-buildifier` at `rev: 6.3.3` with the `buildifier` and `buildifier-lint` hooks, so a contributor who installed pre-commit gets a check on commit, and nobody else does. CI is Bazel's own: `.bazelci/presubmit.yml` imports nine task files (`android.yml`, `bzlmod.yml`, `configurations.yml`, `frontend.yml`, `misc.yml`, `rules.yml` and three tutorial files), each a list of `tasks` with a `working_directory`, `build_targets` and `test_targets`, and none of them runs buildifier. `.github/` holds only a funding file, and `renovate.json` enables the `bazel`, `bazel-module`, `bazelisk` and `github-actions` managers. The agent counts what the check would cover: the BUILD, `BUILD.bazel`, `.bzl`, `WORKSPACE` and `MODULE.bazel` files across the example directories, forty of them module files.

It then runs the current buildifier release over the tree in check mode, `buildifier -mode=check -r .`, and again with `-lint=warn`, and reads what comes back rather than assuming a clean tree. In this repository the format check lists four files that would be rewritten: two `MODULE.bazel` files under `bzlmod/05-integrate_third_party_package_manager/`, `configurations/auto_configured_builds/MODULE.bazel` and `rules/depsets/foo.bzl`. The lint pass adds `module-docstring` warnings on three `.bzl` files, `configurations/cc_binary_selectable_copts/defs.bzl`, `configurations/cc_test/defs.bzl` and `rust-examples/09-oci-container/build/container.bzl`, each saying the file has no module docstring. The agent fixes the four formatting hits by running buildifier in fix mode on those files only, reads each diff to confirm it is whitespace and ordering, and adds a one-line docstring to the three `.bzl` files describing what each defines, since a docstring that says nothing is worse than the warning.

The CI change goes where this repository's CI lives. BazelCI reads a top-level `buildifier:` key in the pipeline configuration, so the agent adds `buildifier: latest` at the top of `.bazelci/presubmit.yml`, above the `imports`, which makes every presubmit run gain a Buildifier step in check and lint mode over the whole checkout; the longer form with `version` and a comma-separated `warnings` list is there for the day a maintainer wants to narrow the lint set. Because a repository that is not on BazelCI needs the same check from GitHub Actions, the pull request also adds `.github/workflows/buildifier.yml`: a job that downloads a pinned `buildifier-linux-amd64` release binary, verifies its checksum, and runs `buildifier -mode=check -lint=warn -r .` on pull requests and pushes to `main`, with the version in one place so Renovate, which already watches GitHub Actions here, can bump it. The pre-commit hook's `rev` is raised to the same release so the three tools agree on what clean means.

To check it, the agent runs the exact command the workflow will run from a clean checkout of its branch and shows it exits zero, then reverts one of the fixed files and runs it again to show the non-zero exit and the file it names. It runs `bazel build //...` in the tutorial directory whose `.bzl` it touched, so the docstring change is shown to be inert, and it runs the pre-commit hook at the new revision over the same files to show the two agree.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a buildifier check to CI for this Bazel repository. Read how Starlark is checked today: any pre-commit configuration, the .bazelci pipeline files and the GitHub Actions workflows. Run the current buildifier release over the whole tree in check mode and in lint mode and read what it reports. Fix the formatting hits by running buildifier in fix mode on those files only, and fix each lint warning by hand with a change that reads well rather than one that silences it. Add the check to CI where this repository's CI runs: the buildifier key in the BazelCI configuration if there is one, and a GitHub Actions workflow that downloads a pinned, checksum-verified buildifier binary and runs it in check and lint mode on pull requests. Align any pre-commit hook to the same buildifier version. Run the CI command from a clean checkout to show it passes, revert one fix to show it fails and names the file, build a target in a directory you changed, and open a pull request with the commands and their output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes the files buildifier flagged, adds the `buildifier` key to the BazelCI configuration and a workflow under `.github/workflows/`, and raises the pre-commit hook's revision. Its description lists each file the format check named and what changed in it, each lint warning and the docstring that answered it, and then the two runs of the CI command: the passing one from the clean branch and the failing one with a fix reverted, so a reviewer can see what a contributor will see when they forget to format.

A reviewer reads the three docstrings, which are the only wording in the change, and decides whether buildifier's default lint set is right or whether a warning or two should be narrowed by name at first. After merging, a pull request with an unformatted BUILD file fails on the Buildifier step with the file path in the log, and the fix is `buildifier -r .` on the contributor's machine.

## Run it on every Bazel repository in the terminal

A developer who has just run buildifier by hand sends this body from their own machine with the repository in `resources` and reads the pull request from the console when the webhook on their API key reports the run. A platform team that owns many Bazel repositories sends one request per repository, each with a `request_id` that is a UUID v5 of the repository's full name, so a script run twice returns the runs already started rather than a second set of pull requests.

Each run reads its own CI: a repository with no `.bazelci` directory gets only the GitHub Actions workflow, one whose workflow already runs buildifier gets the lint mode and the checksum it is missing, and one with a clean tree gets a pull request that adds the check and changes no Starlark.

## Why run it on Rush?

The check is one command; the work is reading what it reports on this tree and fixing each hit in a way the maintainers would accept, then proving the gate catches what it should. The agent runs buildifier in its own sandbox over every Starlark file, keeps each file it named and the diff it produced in the run's record, and runs the CI command both passing and failing so the pull request shows the gate working rather than asserting it.

It also fits the repository's own CI rather than assuming GitHub Actions: the BazelCI key where the presubmits already run, the Renovate managers that already watch versions here, the pre-commit revision that contributors already use. Many repositories with many layouts get many pull requests, each with its own list of hits and its own place for the check.

## Frequently asked questions

### Will it reformat every BUILD file in the repository?

Only the ones buildifier's check mode names, and only by running buildifier on those files, so the diff is whitespace and attribute ordering. The pull request lists each file, and a clean tree gets a pull request that adds the check and touches no Starlark.

### Which lint warnings does it enable?

Buildifier's default warning set in warn mode, with each warning the tree currently triggers fixed in the same pull request so the first CI run is green. The pull request names each warning, and a maintainer can narrow the set with the comma-separated `warnings` key in the BazelCI configuration and the matching `-warnings` flag in the workflow.

### How is the buildifier version pinned?

The GitHub Actions workflow downloads a named release binary and checks its SHA-256 before running it, with the version in one place that Renovate or Dependabot can bump. The BazelCI step uses its own `version` key, and the pre-commit hook's `rev` is set to the same release so all three agree.

### We only use BazelCI. Do we need the GitHub workflow?

No. The agent adds the `buildifier` key to the BazelCI configuration, which gives every presubmit a Buildifier step in check and lint mode, and the GitHub workflow is there for repositories whose CI runs on Actions. The pull request keeps the two in separate commits so either can be dropped.

## More Bazel jobs

- [Generate compile_commands.json for a Bazel C++ Project](https://getrush.ai/run/add-compile-commands/bazel/)
- [Add Code Coverage to CI for a Bazel Repository](https://getrush.ai/run/add-coverage-to-ci/bazel/)
- [Set Up GitHub Actions CI for a Bazel Repository](https://getrush.ai/run/add-github-actions-ci/bazel/)

## More jobs like this: Hand off a long task

- [Add a Bundle Size Budget to a Vite App](https://getrush.ai/run/add-bundle-size-budget/vite/)
- [Add a Bundle Size Check to a Lit Component](https://getrush.ai/run/add-bundle-size-check/lit/)
- [Add a Bundle Size Check to a SolidJS App](https://getrush.ai/run/add-bundle-size-check/solidjs/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
