Skip to content

Publish a check plugin to the BSR#

Publishing a Buf check plugin to the BSR lets other workspaces reference the plugin’s rules in their buf.yaml without installing the binary locally. The plugin must be compiled as a WebAssembly (Wasm) binary.

This page uses the rpc-suffix plugin built in Go from the check plugin tutorial as the example. Buf documents the Go authoring path; the underlying Bufplugin framework is language-agnostic, so other languages that can target Wasm work in principle, just without a step-by-step Buf-side guide.

Compile to Wasm#

The Wasm binary must target WASI preview1 (the wasip1 syscall API) and end in .wasm. The Buf CLI treats any plugin file without that suffix as a native binary.

For a Go plugin, set the Go cross-compile variables and build:

$ GOOS=wasip1 GOARCH=wasm go build -o rpc-suffix.wasm ./cmd/rpc-suffix

The output rpc-suffix.wasm is what gets uploaded.

Push the plugin#

buf plugin push uploads the Wasm binary to the BSR:

$ buf plugin push buf.build/acme/rpc-suffix \
  --binary=rpc-suffix.wasm \
  --create \
  --create-type=check \
  --create-visibility=public

The flags break down as follows:

  • --binary (required): path to the Wasm file.
  • --create (first push only): creates the plugin in the BSR if it doesn’t already exist. Subsequent pushes ignore the flag.
  • --create-type=check (first push only): identifies the new plugin as a check plugin. Other types exist; check is the right one for buf lint and buf breaking rules.
  • --create-visibility (required with --create): public or private.

For the full flag list, see the buf plugin push reference.

Use the published plugin#

In the workspace that wants to consume the plugin, add it under plugins in buf.yaml and reference its rules in lint.use (or breaking.use):

 version: v2
 modules:
   - path: proto
     name: buf.build/tutorials/lint-plugin
 lint:
   use:
     - STANDARD
+    - RPC_SUFFIX
+plugins:
+  - plugin: buf.build/acme/rpc-suffix

RPC_SUFFIX is the rule ID defined inside the plugin’s Go code (see the tutorial).

Pin the plugin commit by running buf plugin update, which resolves every entry under plugins and writes a pinned commit ID and digest into buf.lock:

$ buf plugin update

For the full flag list, see the buf plugin update reference.

buf lint (and buf breaking, where applicable) then run the plugin’s rules alongside Buf’s built-ins:

$ buf lint

proto/pet/v1/pet.proto:30:3:method name should not end with "Method" (buf.build/acme/rpc-suffix)