buf push: Publish a Module to the Buf Schema Registry
buf push uploads the module named in buf.yaml to the Buf Schema Registry so other teams can depend on it; --label tags the upload.
Publishing to BSR lets downstream repos pull your protos as a dependency and lets remote plugins generate against them. The common CI snag is authentication.
What it does
buf push compiles the module, uploads it to the BSR repository named by the name: (v1) or modules[].name: (v2) field in buf.yaml, and creates a commit there. --label attaches a moving label (for example a release channel) to that commit so consumers can pin to a name instead of a raw commit.
Common usage
# authenticate non-interactively in CI
echo "$BUF_TOKEN" | buf registry login --token-stdin
# push and apply a label
buf push --label main
# buf.yaml (v2)
# version: v2
# modules:
# - path: proto
# name: buf.build/acme/petapisFlags and options
| Flag | What it does |
|---|---|
| --label <name> | Attach a label to the pushed commit (repeatable) |
| --create | Create the BSR repository if it does not exist |
| --create-visibility <v> | public or private when creating the repo |
| --source-control-url <url> | Record the commit URL with the upload |
| BUF_TOKEN (env) | API token used for buf registry login --token-stdin |
In CI
Store the BSR token as a secret and pipe it via buf registry login --token-stdin; never echo it into logs. Push on merges to your default branch with --label main so consumers tracking that label get the latest schema. The name: in buf.yaml must match the BSR repo exactly.
Common errors in CI
"Failure: you are not authenticated. Set the BUF_TOKEN ... or run buf registry login" means no valid token; log in with --token-stdin. "Failure: <name> does not exist" means the BSR repository is missing; add --create or create it in the UI. "Failure: ... a module name must be set ... in buf.yaml" means the name: field is absent.