The Buf Schema Registry provides generated SDKs for Go from modules and plugins using
go get, just like any other Go
library. It generates SDKs automatically when you push schema changes, which eliminates the need to manage a Protobuf
toolchain or generate code locally.
See the tutorial for instructions on how to access generated SDKs from the BSR directly.
The BSR Go module proxy implements the GOPROXY protocol for Buf modules by generating SDKs on the
fly—Go code stubs aren't generated until you request them using
go get. Once generated, they're cached, and the cached
SDKs are returned from subsequent requests.
Using Go modules
The key to consuming from the BSR Go module proxy is choosing the right Go module path. The import path for generated Go code has this format:
In this example,
buf.build/gen/go/connectrpc/eliza/connectrpc/go, the BSR generates code for the
connectrpc/eliza module using the
connectrpc/go. plugin. This SDK depends on
buf.build/gen/go/connectrpc/eliza/protocolbuffers/go as well—
connect-go has a dependency on code generated by the
protocolbuffers/go plugin, and generated SDKs automatically include plugin
$ go get buf.build/gen/go/connectrpc/eliza/connectrpc/goOutputgo: downloading buf.build/gen/go/connectrpc/eliza/connectrpc/go v1.11.0-20230727062025-d8fbf2620c60.1 go: added buf.build/gen/go/connectrpc/eliza/connectrpc/go v1.11.0-20230727062025-d8fbf2620c60.1
By default, when you
go get a Buf module, the BSR generates code from the most recent
reference for the module. However, you can also install a specific module
version by referencing an explicit version or a branch name with the
@ syntax. To discover SDK versions, you can
browse a repository's SDKs page, which has installation instructions and an interactive UI.
To get the generated SDK for the latest version of the module:
$ go get buf.build/gen/go/connectrpc/eliza/connectrpc/go@latest
To get the generated SDK for the module at a commit:
$ go get buf.build/gen/go/connectrpc/eliza/connectrpc/go@d8fbf2620c604277a0ece1ff3a26f2ff
To get the generated SDK for the module at a tag:
$ go get buf.build/gen/go/connectrpc/eliza/connectrpc/go@foo
The BSR supports commits on branches. This feature enables you to push unreleased Protobuf file changes and consume generated code without affecting the main branch.
To get the generated SDK for the module on a branch:
$ go get buf.build/gen/go/connectrpc/eliza/connectrpc/go@dev
References with names that contain
/ are not compatible with the Go generated SDKs versioning scheme.
With SDK versions (valid semver):
- The version core is the plugin version 1.11.0
- The semver pre-release version is composed of:
- module commit timestamp (YYYYMMDDHHMMSS) 20230727062025
- module commit short name (12 characters) d8fbf2620c60
- The final identifier is the plugin revision 1 for the plugin version
Most users will likely use
@latest, but if you need to reference a version explicitly, you can do so like this:
$ go get firstname.lastname@example.org
For commits on branches, the commit timestamp component of the version is always zeroed out to easily
differentiate package versions using commits on branches that aren't
Private generated SDKs
When using SDKs generated from private BSR repositories, you'll need to authenticate by including a personal API token for local use or a Bot user's API token for CI workflows.
go tool authenticates with proxies using
.netrc credentials or credentials
directly specified in GOPROXY URLs. See the Authentication
page for instructions on setting up your token and authenticating with
You can also authenticate using direct credentials:
As mentioned in the Go docs on using direct credentials, use caution when taking this approach, as environment variables may appear in shell history and in logs.
Private modules are only accessible to authorized users and can't be pulled through the default module proxy at
https://proxy.golang.org or have their checksums verified with the public checksum database at https://sum.golang.org/.
To access private modules you need to specify a combination of
There are two possible ways to configure Go for private modules:
GOPRIVATE=buf.build/gen/go. This implicitly sets
GONOSUMDBto the same value, causing Go to use the
directstrategy for fetching directly from BSR without going through the public proxy.
GONOPROXYincludes the Buf registry, this is not compatible with specifying auth directly in
GOPROXY. Only netrc-based auth is supported in this configuration.
GONOSUMDB=buf.build/gen/go. This instructs Go to try a module from Buf before falling back to the existing configured proxies. This works both for netrc and direct authentication.
Modify the Go environment using the
export command in your shell or with the
go env -w command to persist the
$ export GONOSUMDB=$GONOSUMDB,buf.build/gen/go
For more information, see the official private modules documentation.
For a full list of supported plugins, navigate to the BSR plugins page and search for Go.
- Try the generated SDKs tutorial to learn how to generate SDKs from the BSR.