protoc-gen-go: Generate Go Message Code in CI
protoc-gen-go is a protoc plugin that turns proto messages into Go structs; protoc invokes it whenever you pass --go_out.
protoc-gen-go generates only the message types (not gRPC services). The number-one CI failure is the plugin binary not being on PATH.
What it does
protoc-gen-go is a binary that protoc executes when it sees --go_out. It reads the compiled descriptors on stdin and writes *.pb.go files containing Go structs, getters, and marshaling for each message. It does not generate service/client code; that is protoc-gen-go-grpc or connect-go.
Common usage
# install the plugin (must land on PATH, e.g. $(go env GOPATH)/bin)
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
export PATH="$PATH:$(go env GOPATH)/bin"
protoc -I proto \
--go_out=gen --go_opt=paths=source_relative \
proto/api/v1/user.protoFlags and options
| Flag / opt | What it does |
|---|---|
| --go_out=<dir> | Invoke protoc-gen-go and write Go to <dir> |
| --go_opt=paths=source_relative | Mirror the .proto directory layout |
| --go_opt=module=<prefix> | Strip a module path prefix from output paths |
| --go_opt=M<proto>=<import> | Override the Go import path for an imported proto |
| --plugin=protoc-gen-go=<path> | Use a plugin binary not on PATH |
In CI
Install the plugin with go install ...@<pinned-version> and add $(go env GOPATH)/bin to PATH in the same job. Pin the version: a floating @latest can regenerate code and produce a spurious "generated files changed" diff. Many teams move this whole flow to buf generate with remote plugins to avoid the install entirely.
Common errors in CI
"protoc-gen-go: program not found or is not executable" means the plugin is not on PATH after go install; export $(go env GOPATH)/bin. "--go_out: protoc-gen-go: Plugin failed with status code 1" is a downstream plugin error, often a missing M mapping for an import. The old "protoc-gen-go: unable to determine Go import path ... please specify ... go_package" appears when a .proto lacks a go_package option.