buf generate: Code Generation With buf.gen.yaml
buf generate reads buf.gen.yaml and runs each listed plugin against your module, replacing long protoc command lines with declarative config.
Instead of a sprawling protoc invocation, buf generate centralizes plugins and output dirs in buf.gen.yaml. CI either uses local plugins on PATH or buf remote plugins (no install).
What it does
buf generate compiles the module and invokes every plugin in the plugins: list of buf.gen.yaml, writing to each plugin's out: directory. Plugins are either local binaries (local: protoc-gen-go), buf remote plugins (remote: buf.build/protocolbuffers/go), or path-resolved by name.
Common usage
# buf.gen.yaml
# version: v2
# plugins:
# - remote: buf.build/protocolbuffers/go
# out: gen
# opt: paths=source_relative
# - remote: buf.build/grpc/go
# out: gen
# opt: paths=source_relative
buf generate
buf generate --template buf.gen.yaml --path proto/api/v1
buf generate https://github.com/acme/protos.git#branch=mainFlags and options
| Flag | What it does |
|---|---|
| --template <file> | Use a specific buf.gen.yaml (default is ./buf.gen.yaml) |
| -o, --output <dir> | Base directory all plugin outputs are written under |
| --path <path> | Generate only for the given files or directories |
| --include-imports | Also generate code for imported files |
| --include-wkt | Also generate the well-known types |
| local / remote (in YAML) | Run a PATH binary vs a buf.build remote plugin |
In CI
Remote plugins (remote: buf.build/...) need no toolchain install and pin a plugin version, which makes CI reproducible. If you must use local: plugins, install them in the job and confirm they are on PATH before buf generate.
Common errors in CI
"Failure: plugin protoc-gen-go: program not found or is not executable" means a local: plugin is missing from PATH; go install it or switch to a remote: plugin. "Failure: <template>: unknown field ... in plugin" usually means a v1/v2 schema mismatch (v2 uses remote:/local:, older v1 used plugin:). After generating, "git diff exited with code 1" in a verify step means generated files are out of date; regenerate and commit.