buf-cli-lint-breaking-build

Overview

Wraps three buf CLI commands - build, lint, breaking - as the proto-PR gate, per buf.build/docs/cli/quickstart/. Pairs with protobuf-versioning-strategy-reference for the catalog of what counts as breaking and why.

When to use

• Adding buf as the proto lint + breaking-change gate on a new repo.
• A PR changes .proto files - need to gate the merge.
• Investigating a buf breaking failure - what rule fired?
• Configuring buf for a monorepo with multiple proto modules.

Authoring

Install

Per buf docs, install via Homebrew, Go install, or release binary. Version 1.32.0 or higher is required. Verify:

buf --version
# 1.32.0 or higher

Configure buf.yaml

The v2 format per buf.build/docs/cli/quickstart/:

version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE          # default; choose per protobuf-versioning-strategy-reference

STANDARD is the recommended lint rule set; it enforces conventions like "Field name should be lower_snake_case" and "Service name should be suffixed with Service".

The choice of breaking.use (FILE / PACKAGE / WIRE_JSON / WIRE) follows the per-deployment-model logic in protobuf-versioning-strategy-reference.

Configure buf.gen.yaml (codegen)

version: v2
managed:
  enabled: true
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt: paths=source_relative

managed: enabled: true automatically sets file options without hand-coding (e.g., go_package).

Running

Local validation pipeline

buf build && buf lint && buf breaking --against ".git#branch=main"

Three gates in order: compile, lint, breaking. All three must pass before merge.

buf build

buf build
# Silent exit on success

Compiles every .proto in the workspace. Silent → success. Any output → error. Equivalent to protoc compilation but reads buf.yaml for paths.

buf lint

buf lint
# Emits violations as: <file>:<line>:<col>:<msg>

Validates against the configured rule set. Common failures:

buf breaking

buf breaking --against ".git#branch=main"
# Compares working tree against main branch

Baselines (per buf docs):

Output on violation:

proto/foo.proto:42:5: Field "old_name" with type "string" no longer exists (rule FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED).

Per buf breaking rules: each violation cites the rule that fired so you know which category constraint was violated.

Parsing results

CLI output (text, default)

Each violation: <file>:<line>:<col>: <message> (rule <RULE_ID>).

Pipe to grep / awk for counts:

buf breaking --against ".git#branch=main" 2>&1 | tee buf-breaking.log
wc -l buf-breaking.log

Machine-readable output

buf lint --error-format=json
# Emits: [{"path":"...","start_line":...,"start_col":...,"end_line":...,"type":"FIELD_LOWER_SNAKE_CASE","message":"..."}]

buf breaking --against ".git#branch=main" --error-format=json

For consumption by a unified reporter.

CI integration

Gate buf build / lint / breaking on PRs that touch .proto, buf.yaml, or buf.gen.yaml. Key gotcha: fetch-depth: 0 so git has the baseline commit available. Full GitHub Actions workflow plus the failure PR-comment: references/ci-integration.md.

Anti-patterns

Limitations

• Semantic vs wire breakage. Per protobuf-versioning-strategy-reference, buf detects binary/codegen breakage. Semantic meaning changes ("field now means net price, not gross") are undetectable.
• No cross-service compatibility. This is single-service schema lint. For service-to-service contract testing see protobuf-compat-checking.
• BSR features require auth. Remote plugins, registry pushes, and buf.build/... baselines need a BSR account.
• JSON-name detection is in WIRE_JSON only. Services that use only binary won't see JSON name changes detected.
• Doesn't generate code automatically. buf generate is a separate step; this skill scopes to gating.

References

• buf CLI quickstart: buf.build/docs/cli/quickstart/.
• buf breaking rules: buf.build/docs/breaking/rules.
• Companion catalog: protobuf-versioning-strategy-reference.
• Status code vocabulary: grpc-status-code-mapping-reference.
• Sibling tools: ghz-load, grpcurl-cli, grpc-mock.
• Cross-service contract testing: protobuf-compat-checking.