buf build: Compile Proto Into an Image for CI
buf build compiles your proto module into a buf image (a FileDescriptorSet plus metadata) and fails fast on any parse or import error.
buf build is the cheapest CI gate: it just compiles. If buf build fails, every later step (lint, breaking, generate) would fail too, so run it first.
What it does
buf build reads the module defined by buf.yaml (or a workspace buf.work.yaml), compiles every .proto, and either validates only or writes an image with -o. The image is a serialized set of file descriptors that buf breaking and buf generate can consume instead of re-reading source.
Common usage
# validate the current module compiles
buf build
# write a buf image to a file
buf build -o image.binpb
# write a raw protoc-style FileDescriptorSet
buf build -o image.binpb --as-file-descriptor-set
# build a specific input (dir, tarball, or git ref)
buf build https://github.com/acme/protos.git#branch=mainFlags and options
| Flag | What it does |
|---|---|
| -o, --output <file> | Write the image (.binpb / .json) instead of validating only |
| --as-file-descriptor-set | Emit a bare FileDescriptorSet (protoc-compatible) |
| --path <path> | Limit the build to specific files or directories |
| --exclude-imports | Do not include imported files in the output image |
| --exclude-source-info | Drop source code info to shrink the image |
| --error-format json | Machine-readable diagnostics for CI annotations |
In CI
Build the image once and feed it to later steps with --against / input args so each command does not recompile. Use --error-format=github-actions to get inline file annotations on a pull request.
Common errors in CI
"Failure: <file>: import "x.proto": file does not exist" means an import is unresolved against the module roots in buf.yaml. "Failure: <buf.yaml>: ... could not be unmarshaled" means a malformed or wrong-version buf.yaml (check the version: v1 / version: v2 key). "Failure: no .proto files were targeted" means the module roots point at an empty or wrong directory.