Bazel Gazelle "BUILD files out of date" - Fix gazelle in CI

Gazelle generates and updates BUILD files from your sources. CI often runs gazelle in diff mode and fails if the committed BUILD files differ from what Gazelle would produce - typically because someone added a source or dependency without re-running it.

What this error means

A "gazelle check" CI step fails showing a diff in BUILD files, or a build fails because a new source file has no rule. The fix is to run Gazelle and commit the regenerated files. Deterministic for the source tree.

Bazel / gazelle output

ERROR: BUILD files are out of date. Run `bazel run //:gazelle` and commit.

--- a/app/BUILD.bazel
+++ b/app/BUILD.bazel
@@ go_library srcs missing: ["handler.go"]

Common causes

Sources or deps changed without re-running Gazelle

A new .go/.ts file or a new import means the generated BUILD no longer matches; the diff check flags it.

External repos not updated

New module dependencies require gazelle update-repos (or the bzlmod equivalent) to be reflected in the build files.

Missing or wrong gazelle directive

A # gazelle: directive controlling resolution/exclusion may be missing, so Gazelle generates something CI does not expect.

How to fix it

Regenerate BUILD files and commit

Run the Gazelle target, then commit the updated BUILD files.

Terminal

bazel run //:gazelle
git add -A '**/BUILD.bazel' && git commit -m "gazelle: regenerate BUILD files"

Update external repo mappings

When dependencies change, refresh the generated repo rules too.