use-buf-plugins

Use Buf Plugins

Make code generation reproducible across languages and environments. Prefer an established generator, pin its version, preserve source-relative package structure, and verify generated output.

Inspect the Existing Generation Contract

1. Read repository instructions, every applicable buf.gen*.yaml, generation script, CI workflow, package manifest, and generated directory convention.
2. Identify each required artifact: message runtime, gRPC client/server, gateway, OpenAPI, language typing, or framework bindings.
3. Record plugin source, version/revision, options, invocation strategy, input scope, output path, and runtime requirements.
4. Do not replace a working generator or rearrange generated paths without an explicit requirement.

Choose Remote or Local Deliberately

Use a BSR remote plugin when network access is reliable and centralized execution is acceptable. Pin the upstream plugin version and revision when available; do not rely on latest for reproducible generation.

Use a local plugin when:

• generation must work offline or in an isolated network;
• the BSR is unavailable;
• authentication or codegen rate limits make remote generation unreliable;
• a private/custom plugin cannot run remotely;
• CI requires locally controlled binaries or images.

Remote generation sends the Protobuf input to the configured BSR executor. Confirm that this is acceptable for private schemas. Authenticate with the repository's approved mechanism when increased BSR limits are needed; never embed tokens in config.

Read references/remote-and-local.md before changing plugin execution mode.

Source and Package Local Plugins Reproducibly

• Prefer the plugin author's official binary/package or the upstream definitions in bufbuild/plugins.
• Treat each upstream plugin Dockerfile, version, and revision as immutable build input.
• A maintained mirror may build selected upstream bufbuild/plugins Dockerfiles into OCI images. Verify its source mapping, image entrypoint, version tag, platforms, provenance, and update cadence before depending on it.
• If using a maintained buf-build mirror, understand the convention: an upstream path like plugins/<family>/<plugin>/<version>/Dockerfile is published as an image whose repository identifies <family>-<plugin> and whose tag identifies <version>. Reinspect the mirror documentation instead of hardcoding one publisher, version, or registry.
• If the maintained image is acceptable, consume a pinned digest or immutable version. Otherwise build the upstream definition locally.
• Invoke $use-docker-buildx-for-building before building or smoke-testing any plugin OCI image. Follow its platform, --load, naming, secret, runtime, and cleanup requirements.