protoc / plugin version skew in CI

By Kaveh Alemi·Latchkey

protoc and each codegen plugin evolve independently. When CI installs different versions than you use locally, generated code drifts or the plugin errors on newer descriptor features. Pinning every version keeps output reproducible.

What this error means

CI produces a different generated diff than local, or the plugin fails at runtime with "this file was generated by an older version of protoc-gen-go" or a descriptor incompatibility.

protoc-gen-go-grpc: This file was generated with a newer version of
protoc-gen-go-grpc than is supported by the installed runtime.
--go-grpc_out: protoc-gen-go-grpc: Plugin failed with status code 1.

Common causes

Unpinned plugin installs pull latest

go install protoc-gen-go@latest in CI installs whatever is newest, which may not match your local plugin or the runtime library version.

protoc and plugins advance at different rates

A newer protoc emits descriptor features an older plugin does not support, or vice versa, so the generated code is inconsistent.

How to fix it

Pin protoc and every plugin to exact versions

1. Pin protoc with a version, not a floating tag.
2. Install each plugin at a fixed version (no @latest).
3. Keep the same versions locally so diffs match.

go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.34.2
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.5.1

Manage plugin versions in buf.gen.yaml

Declare remote plugin versions in buf.gen.yaml so every run uses the identical plugin, independent of the runner.

version: v2
plugins:
  - remote: buf.build/protocolbuffers/go:v1.34.2
    out: gen

How to prevent it

• Never use @latest for codegen tools in CI.
• Pin protoc and all plugins to exact versions, committed in config.
• Add a "generate then git diff --exit-code" check to catch drift.

Frequently asked questions

Related guides

References

• GitHub Actions documentation