[Go to site: main page, start]
Skip to content

Buf check plugins#

A Buf check plugin is a binary that contributes custom lint or breaking-change rules to buf lint and buf breaking alongside Buf’s built-ins. This is distinct from remote plugins, which run code-generation plugins from buf.gen.yaml; check plugins extend buf.yaml and produce diagnostics, not generated code.

This page orients plugin authors. For the consumer side (declaring a plugin under plugins: in buf.yaml and referencing its rules), see Configuring lint or Configuring breaking-change detection.

How a check plugin fits into a workspace#

In a consumer’s buf.yaml, a plugin entry references its rules under lint.use or breaking.use:

buf.yaml
version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
    - RPC_SUFFIX
plugins:
  - plugin: rpc-suffix

The plugin: field accepts three forms:

  • A binary name on ${PATH} (rpc-suffix in the example above).
  • A relative or absolute path to a local Wasm file (./rpc-suffix.wasm).
  • A remote BSR plugin reference (buf.build/acme/rpc-suffix), which the Buf CLI resolves through buf.lock.

The framework#

Three layers stack underneath:

  • The Bufplugin spec defines the Protobuf API a plugin implements (rule specs, request and response shapes, option handling).
  • PluginRPC is the RPC framework Bufplugin uses for transport between the Buf CLI and the plugin process.
  • bufplugin-go is the Go SDK that wraps both for plugin authors writing in Go.

For a Go plugin, the SDK handles the wiring; you implement rule handlers and pass them to check.Main. Other languages implement the Bufplugin API directly over PluginRPC.

Buf’s own built-in lint and breaking-change rules run on this same framework, so anything you can do in built-ins is reachable from a plugin. The consumer-side buf plugin CLI is generally available; the authoring framework is still maturing, so the surface area documented in bufplugin and pluginrpc may change.

Next steps#