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/. The catalog of what counts as breaking and why lives in references/versioning-strategy.md (+ references/buf-breaking-rules.md).

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 references/versioning-strategy.md

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 references/versioning-strategy.md.

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:

Failure	Rule	Fix
Field name "userId" should be lower_snake_case	FIELD_LOWER_SNAKE_CASE	Rename to user_id
Service "Users" should be suffixed with "Service"	SERVICE_SUFFIX	Rename to UsersService
Message "user_data" should be UpperCamelCase	MESSAGE_UPPER_CAMEL_CASE	Rename to UserData
Enum value should be SCREAMING_SNAKE_CASE	ENUM_VALUE_UPPER_SNAKE_CASE	Rename

buf breaking

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

Baselines (per buf docs):

Baseline	Use
".git#branch=main"	Compare against main branch (CI default)
".git#tag=v1.0.0"	Compare against a release tag
".git#subdir=path/to/proto"	Sub-directory baseline (monorepo)
"path/to/image.bin"	Pre-built buf build image file
"buf.build/owner/module"	Compare against published BSR image

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

Anti-pattern	Why it fails	Fix
Skipping buf breaking on PR	Subtle wire breakage merges; consumers crash at deploy time	Always gate; never --ignore blanket
Comparing against the PR's own merge base	Self-baseline; no detection	Use ".git#branch=main"
fetch-depth: 1 in CI	git can't reach baseline → buf errors	fetch-depth: 0
breaking.use: WIRE for codegen consumers	Generated code break (rename) passes; consumer build fails	Use FILE or PACKAGE per references/versioning-strategy.md
Adding --ignore to suppress a real violation	Silent regression	Use proper reserved + deprecation instead
Lint set MINIMAL for new projects	Misses snake_case + service-suffix conventions early	Use STANDARD from day 1
One buf.yaml per proto file	Doesn't compose; lint runs N times	One buf.yaml at module root
Inconsistent baselines (main vs tag)	Different reviewers see different verdicts	Pick one CI baseline; document

Limitations

• Semantic vs wire breakage. Per references/versioning-strategy.md, 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.
• Versioning + breaking-change catalog: references/versioning-strategy.md (+ references/buf-breaking-rules.md).
• Status code vocabulary: grpc-streaming-test-author (references/status-codes.md).
• Sibling tools: ghz-load, grpcurl-cli, grpc-mock.
• Cross-service contract testing: protobuf-compat-checking.