protoc-gen-go-grpc: Generate Go gRPC Stubs in CI
protoc-gen-go-grpc generates Go gRPC client and server stubs and is invoked by protoc through --go-grpc_out, separate from protoc-gen-go.
Since the modern toolchain split messages from services, you run two plugins: protoc-gen-go for structs and protoc-gen-go-grpc for the gRPC service code.
What it does
protoc-gen-go-grpc generates *_grpc.pb.go files with the server interface, the unimplemented embed, and the client for each service. protoc runs it on --go-grpc_out. You almost always run it alongside protoc-gen-go, since the gRPC stubs depend on the message types the latter generates.
Common usage
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
export PATH="$PATH:$(go env GOPATH)/bin"
protoc -I proto \
--go_out=gen --go_opt=paths=source_relative \
--go-grpc_out=gen --go-grpc_opt=paths=source_relative \
proto/api/v1/user.protoFlags and options
| Flag / opt | What it does |
|---|---|
| --go-grpc_out=<dir> | Invoke protoc-gen-go-grpc and write stubs to <dir> |
| --go-grpc_opt=paths=source_relative | Mirror the .proto directory layout |
| --go-grpc_opt=require_unimplemented_servers=false | Do not require the Unimplemented embed |
| --plugin=protoc-gen-go-grpc=<path> | Use a plugin binary not on PATH |
In CI
Install both protoc-gen-go and protoc-gen-go-grpc, pin both versions, and run them in one protoc command so the message and service code stay in sync. The require_unimplemented_servers=false option helps when you do not want the forward-compatible embed forced on every server implementation.
Common errors in CI
"protoc-gen-go-grpc: program not found or is not executable" means the plugin is missing from PATH. A Go build failure after generation like "cannot use ... does not implement UserServiceServer (missing mustEmbedUnimplementedUserServiceServer method)" means your server struct must embed the generated Unimplemented type, or you should set require_unimplemented_servers=false. Mismatched versions of protoc-gen-go and the grpc plugin can also produce build errors in the generated code.