Add a CI workflow to lint, generate, and format code

.github/workflows/ci.yaml

@@ -0,0 +1,57 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+permissions: read-all
+jobs:
+  checkgenerate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Pin Bazel to .bazelversion
+        run: echo "USE_BAZEL_VERSION=$(cat .bazelversion)" >> "$GITHUB_ENV"
+      - name: Setup Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        with:
+          go-version: stable
+          check-latest: true
+      - name: Cache bazel
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.cache/bazelisk
+            ~/.cache/bazel
+          key: ${{ runner.os }}-bazel-checkgenerate-${{ hashFiles('.bazelversion', 'MODULE.bazel.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bazel-checkgenerate-
+      - name: Lint
+        run: make lint
+      - name: Check generated files
+        run: make checkgenerate
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Pin Bazel to .bazelversion
+        run: echo "USE_BAZEL_VERSION=$(cat .bazelversion)" >> "$GITHUB_ENV"
+      - name: Cache bazel
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.cache/bazelisk
+            ~/.cache/bazel
+          key: ${{ runner.os }}-bazel-examples-${{ hashFiles('.bazelversion', 'examples/**/MODULE.bazel.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bazel-examples-
+      - name: Build examples
+        run: |
+          for dir in examples/*/; do
+            echo "::group::bazel build in ${dir}"
+            (cd "${dir}" && bazel build //...)
+            echo "::endgroup::"
+          done

BUILD.bazel

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 load("@bazel_gazelle//:def.bzl", "gazelle")
-load("@com_github_bazelbuild_buildtools//buildifier:def.bzl", "buildifier")
+load("@com_github_bazelbuild_buildtools//buildifier:def.bzl", "buildifier", "buildifier_test")
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
 
 # gazelle:prefix github.com/bufbuild/rules_buf
@@ -37,8 +37,10 @@ stardoc(
     out = "buf-rules.md",
     input = "//buf:defs.bzl",
     symbol_names = [
-        "buf_lint_test",
         "buf_breaking_test",
+        "buf_dependencies",
+        "buf_format",
+        "buf_lint_test",
     ],
     deps = [
         "//buf:defs",
@@ -48,3 +50,15 @@ stardoc(
 buildifier(
     name = "buildifier",
 )
+
+buildifier_test(
+    name = "buildifier_check",
+    exclude_patterns = [
+        "./.bazelbsp/**",
+        "./.tmp/**",
+        "./bazel-*/**",
+    ],
+    lint_mode = "warn",
+    no_sandbox = True,
+    workspace = "//:MODULE.bazel",
+)

MODULE.bazel

@@ -26,7 +26,8 @@ bazel_dep(name = "rules_proto", version = "7.0.2")
 bazel_dep(name = "rules_go", version = "0.59.0", repo_name = "io_bazel_rules_go")
 bazel_dep(name = "bazel_skylib", version = "1.7.1")
 
-bazel_dep(name = "stardoc", version = "0.7.1", dev_dependency = True, repo_name = "io_bazel_stardoc")
+bazel_dep(name = "rules_shell", version = "0.6.1", dev_dependency = True)
+bazel_dep(name = "stardoc", version = "0.8.1", dev_dependency = True, repo_name = "io_bazel_stardoc")
 
 # We depend on gazelle at runtime to generate our proto_library rules
 bazel_dep(name = "gazelle", version = "0.40.0", repo_name = "bazel_gazelle")

Makefile

@@ -9,11 +9,15 @@ MAKEFLAGS += --no-print-directory
 BIN := .tmp/bin
 COPYRIGHT_YEARS := 2021-2025
 LICENSE_IGNORE := -e /testdata/
-# Commit where bazel support was added
-LICENSE_HEADER_VERSION := dc4b633f0accc5f571c577325ce556a8e988ec4e
+LICENSE_HEADER_VERSION := v1.68.4
 # Set to use a different compiler. For example, `GO=go1.18rc1 make test`.
 GO ?= go
-BAZEL ?= bazel
+BAZEL ?= bazelisk
+# Pin Bazel to .bazelversion so a newer Bazel on PATH doesn't rewrite
+# MODULE.bazel.lock to a higher lockFileVersion. tests.yaml's matrix overrides
+# this via env to exercise multiple Bazel versions.
+USE_BAZEL_VERSION ?= $(shell cat .bazelversion)
+export USE_BAZEL_VERSION
 
 .PHONY: help
 help: ## Describe useful make targets
@@ -33,11 +37,39 @@ test: ## Run unit tests
 	$(BAZEL) test //...
 
 .PHONY: format
-format:
+format: ## Format Starlark files with buildifier
 	$(BAZEL) run //:buildifier
 
+.PHONY: lint
+lint: ## Lint Starlark files with buildifier
+	$(BAZEL) test //:buildifier_check
+
 .PHONY: generate
-generate: $(BIN)/license-header ## Regenerate code and licenses
+generate: $(BIN)/license-header ## Regenerate BUILD files, repositories.bzl, license headers, and format
+	@# Tidy first so gazelle_update_repos regenerates repositories.bzl from
+	@# a clean go.mod.
+	$(GO) mod tidy
+	$(BAZEL) run //:gazelle_update_repos
+	$(BAZEL) run //:gazelle
+	@# Regenerate stardoc reference for the public buf rules.
+	$(BAZEL) build //:buf_rule_docs
+	install -m 0644 bazel-bin/buf-rules.md docs/buf-rules.md
+	@# Run go mod tidy, gazelle, and buf_format in each example that
+	@# defines them.
+	@for dir in examples/*/; do \
+		if [[ -f "$${dir}go.mod" ]]; then \
+			echo "$(GO) mod tidy in $${dir}"; \
+			(cd "$${dir}" && $(GO) mod tidy); \
+		fi; \
+		if (cd "$${dir}" && $(BAZEL) query //:gazelle >/dev/null 2>&1); then \
+			echo "$(BAZEL) run //:gazelle in $${dir}"; \
+			(cd "$${dir}" && $(BAZEL) run //:gazelle); \
+		fi; \
+		if (cd "$${dir}" && $(BAZEL) query //:buf_format >/dev/null 2>&1); then \
+			echo "$(BAZEL) run //:buf_format in $${dir}"; \
+			(cd "$${dir}" && $(BAZEL) run //:buf_format); \
+		fi; \
+	done
 	@# We want to operate on a list of modified and new files, excluding
 	@# deleted and ignored files. git-ls-files can't do this alone. comm -23 takes
 	@# two files and prints the union, dropping lines common to both (-3) and
@@ -51,6 +83,11 @@ generate: $(BIN)/license-header ## Regenerate code and licenses
 			--license-type apache \
 			--copyright-holder "Buf Technologies, Inc." \
 			--year-range "$(COPYRIGHT_YEARS)"
+	$(MAKE) format
+
+.PHONY: checkgenerate
+checkgenerate: generate ## Run generate and fail if anything changed
+	git diff --exit-code --stat
 
 $(BIN)/license-header: Makefile
 	@mkdir -p $(@D)

README.md

@@ -66,6 +66,8 @@ Refer to the [docs](https://buf.build/docs/cli/build-systems/bazel) or browse th
 - [buf_breaking_test](https://buf.build/docs/cli/build-systems/bazel#buf-breaking-test)
 - [buf_format](https://buf.build/docs/cli/build-systems/bazel#buf-format)
 
+See [docs/buf-rules.md](docs/buf-rules.md) for the full attribute reference, generated from the rule definitions.
+
 ## Gazelle Extension
 
 The repo also offers a Gazelle extension for generating the rules.

buf/defs.bzl

@@ -20,7 +20,9 @@
 The rules work alongside `proto_library` rule. They support,
 
 - Linting ([buf_lint_test](#buf_lint_test))
-- Breaking change detection ([buf_breaking_test](#buf_breaking_test)) 
+- Breaking change detection ([buf_breaking_test](#buf_breaking_test))
+- Formatting ([buf_format](#buf_format))
+- BSR module dependencies ([buf_dependencies](#buf_dependencies))
 
 Use [gazelle](/gazelle/buf) to auto generate all of these rules based on `buf.yaml`.
 

buf/internal/format.bzl

@@ -1,3 +1,19 @@
+# Copyright 2021-2025 Buf Technologies, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Implementation of the buf_format rule."""
+
 _DOC = """
 buf_format rule formats Protobuf files.
 """

buf/internal/plugin.bzl

@@ -102,5 +102,5 @@ def protoc_plugin_test(ctx, proto_infos, protoc, plugin, config, files_to_includ
         ),
     ]
 
-def _short_path(file, dir_exp):
+def _short_path(file):
     return file.short_path

buf/internal/toolchain.bzl

@@ -30,6 +30,7 @@ declare_buf_toolchains(
  )
 """
 
+# buildifier: disable=canonical-repository
 _TOOLCHAIN_FILE = """
 load("@bazel_skylib//rules:native_binary.bzl", "native_binary")
 
@@ -158,7 +159,7 @@ def _buf_download_releases_impl(ctx):
 
         ctx.report_progress("Downloading " + bin)
         url = "{}/{}/{}".format(repository_url, version, bin)
-        download_info = ctx.download(
+        ctx.download(
             url = url,
             sha256 = sum,
             executable = True,