Testland
Skills & AgentsTopicsBlogAbout
Browse all skills & agents

buf-cli-lint-breaking-build

Wraps the buf CLI for protobuf PR gating: `buf build` (compile .proto), `buf lint` (STANDARD rules: snake_case fields, Service suffix), `buf breaking --against {ref}` (detect wire/codegen breakage vs a git/BSR baseline), and `buf format`. Use as the CI proto-lint + breaking-change gate, or to debug a breaking failure by rule ID (e.g. FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED) and pick the FILE/PACKAGE/WIRE_JSON/WIRE ruleset per consumer. This is the detection TOOL that enforces the rules; for the catalog of what is breaking and why use protobuf-versioning-strategy-reference, and for cross-service schema contract testing use protobuf-compat-checking - not this.

Install with skills.sh (any agent)

npx skills add testland/qa --skill buf-cli-lint-breaking-build
View source

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/ (opens in new window). 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/ (opens in new window):

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:

FailureRuleFix
Field name "userId" should be lower_snake_caseFIELD_LOWER_SNAKE_CASERename to user_id
Service "Users" should be suffixed with "Service"SERVICE_SUFFIXRename to UsersService
Message "user_data" should be UpperCamelCaseMESSAGE_UPPER_CAMEL_CASERename to UserData
Enum value should be SCREAMING_SNAKE_CASEENUM_VALUE_UPPER_SNAKE_CASERename

buf breaking

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

Baselines (per buf docs (opens in new window)):

BaselineUse
".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 (opens in new window): 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-patternWhy it failsFix
Skipping buf breaking on PRSubtle wire breakage merges; consumers crash at deploy timeAlways gate; never --ignore blanket
Comparing against the PR's own merge baseSelf-baseline; no detectionUse ".git#branch=main"
fetch-depth: 1 in CIgit can't reach baseline → buf errorsfetch-depth: 0
breaking.use: WIRE for codegen consumersGenerated code break (rename) passes; consumer build failsUse FILE or PACKAGE per protobuf-versioning-strategy-reference
Adding --ignore to suppress a real violationSilent regressionUse proper reserved + deprecation instead
Lint set MINIMAL for new projectsMisses snake_case + service-suffix conventions earlyUse STANDARD from day 1
One buf.yaml per proto fileDoesn't compose; lint runs N timesOne buf.yaml at module root
Inconsistent baselines (main vs tag)Different reviewers see different verdictsPick one CI baseline; document

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 CI integration

View source (opens in new window)

buf CI integration

Gate buf build, buf lint, and buf breaking on every PR that touches .proto, buf.yaml, or buf.gen.yaml. All three must pass before merge.

GitHub Actions workflow

# .github/workflows/proto-gate.yml
name: proto-gate
on:
  pull_request:
    paths:
      - "**/*.proto"
      - "buf.yaml"
      - "buf.gen.yaml"

jobs:
  buf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0   # Required for `--against ".git#branch=main"`
      - uses: bufbuild/buf-setup-action@v1
        with:
          buf_user: ${{ secrets.BUF_USER }}
          buf_api_token: ${{ secrets.BUF_API_TOKEN }}
      - run: buf build
      - run: buf lint
      - run: buf breaking --against ".git#branch=main"

Key: fetch-depth: 0 so git has the baseline commit available. fetch-depth: 1 makes buf error because it cannot reach the baseline.

The official bufbuild/buf-setup-action and bufbuild/buf-breaking-action are convenient but the raw CLI calls above work without them.

Per-PR failure comment

      - if: failure()
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: proto-gate
          message: |
            ❌ `buf breaking` failed. See log:
            ```
            ${{ steps.breaking.outputs.stdout }}
            ```
            Consult
            protobuf-versioning-strategy-reference
            for whether this change is genuinely required and how
            to do it safely (reserve, add new, deprecate old).

Related skills

ghz-load

Wraps ghz, the gRPC load testing tool, for throughput and latency benchmarking. Covers test invocation (--proto + --call + host:port; or --protoset for compiled descriptors), load parameters (-n total requests, -c concurrency, -r RPS rate limit, -z duration), output formats (json/csv/html/influx-summary for CI consumption), the metrics reported (RPS achieved, latency p50/p95/p99, status-code distribution, errors), and CI integration patterns for regression gating. Use when benchmarking a gRPC service's throughput or detecting latency regressions in CI.

grpc-interceptor-test-author

Authors unit tests for gRPC interceptor logic: Go grpc.UnaryServerInterceptor/UnaryClientInterceptor, Java ServerInterceptor/ClientInterceptor, and grpc-js client interceptors. Covers auth (Unauthenticated on bad token), retry (backoff on Unavailable), logging/tracing (metadata extraction + propagation), error-mapping (status translation), and chained interceptor ordering - by calling the interceptor directly with a spy handler, no live backend. Use when a gRPC interceptor is written or modified. Different test surface from grpc-streaming-test-author (multi-message stream sequences) and grpc-mock (service handler logic) - use those, not this, for streams or handlers.

grpc-mock

Wraps gRPC server-mocking patterns for client-side tests: Go bufconn (in-memory net.Listener via google.golang.org/grpc/test/bufconn) + mockgen-generated interface mocks, Python pytest-grpc fixtures + unittest.mock patching of stubs, JVM grpc-mock library / in-process gRPC server (InProcessServerBuilder), Node @grpc/grpc-js fake server with NewServer-on-port-0. Use when writing client-side tests that need a controllable gRPC server response (success cases, error cases per grpc-status-code-mapping-reference, timeouts, and single-response error injection) without spinning up a real backend. For multi-message streaming-sequence tests (server-streaming, bidi), use grpc-streaming-test-author instead. Distinct from grpcurl-cli (ad-hoc CLI invocation against a real server) and ghz-load (perf against a real server).

grpc-status-code-mapping-reference

Pure-reference catalog of gRPC standard status codes - the 17 canonical codes (OK..UNAUTHENTICATED), their numeric values, semantics, retry behaviour per AIP-194 (only UNAVAILABLE is auto-retry-safe), and the gRPC-to-HTTP status mapping used by grpc-gateway (NOT_FOUND→404, INVALID_ARGUMENT→400, PERMISSION_DENIED→403, UNAUTHENTICATED→401, RESOURCE_EXHAUSTED→429, FAILED_PRECONDITION→400 not 412, ABORTED→409, UNAVAILABLE→503, DEADLINE_EXCEEDED→504, etc.). Use when designing a gRPC service's error vocabulary, writing assertions in gRPC client tests, configuring retry policies, or mapping gRPC errors to HTTP via a gateway. Consumed by buf-cli-lint-breaking-build, ghz-load, grpcurl-cli, grpc-mock, grpc-streaming-test-author.

grpc-streaming-test-author

Workflow-driven skill that builds gRPC streaming-RPC test suites from a proto definition. Classifies each RPC by pattern (unary, server-streaming, client-streaming, bidi), then emits the required categories per pattern - ordering preservation, completion semantics (server close after stream end, client half-close), cancellation, deadline handling, partial-stream failure. Produces skeletons for Go (bufconn + Send/Recv), Python (iterators), JVM (StreamObserver), Node (call.write/end). Use when adding tests for a new streaming RPC or auditing a suite for uncovered categories. Different test surface from grpc-interceptor-test-author (interceptor layer) and grpc-mock (harness); for wire-level streaming semantics use grpc-streaming-tests, not this.

grpcurl-cli

Wraps grpcurl, the curl-equivalent CLI for gRPC. Covers descriptor sources (server reflection default, --import-path + --proto for proto files, --protoset for compiled descriptor sets), service discovery (`list`, `describe`), invoking unary RPCs (`-d '{...}'`, `-d @file.json`, `-d @` for stdin), streaming RPCs (newline-delimited JSON via stdin), TLS configuration (--cacert, --cert, --key, --insecure, --plaintext), header injection (-H 'Authorization: Bearer ...'), and exit codes. Use for ad-hoc gRPC debugging, smoke testing, scriptable PR-time gates, and CLI-based interaction with reflective gRPC services.

protobuf-versioning-strategy-reference

Pure-reference catalog of protobuf3 versioning and breaking-change rules: field-number reservation (reserve on delete; 1..536870911; 19000-19999 reserved), wire-safe vs wire-incompatible changes (add/remove safe with reservation; changing a field number always breaks), compatible type conversions (int32/uint32/int64/uint64/bool; sint32/sint64; string/bytes for UTF-8; enum/int), oneof + map constraints, and buf's four breaking categories (FILE/PACKAGE/WIRE_JSON/WIRE) with rule IDs. Use when designing a schema change or picking a buf breaking ruleset. This is the catalog of what is breaking and why, not a scanner; to detect changes in CI use buf-cli-lint-breaking-build, for the gRPC status-code vocabulary use grpc-status-code-mapping-reference, and for cross-service contract testing use protobuf-compat-checking.