Buf Docs

Appearance

Commits and labels ​

A commit on the Buf Schema Registry (BSR) is an immutable snapshot of a module, identified by a digest. A label is a mutable pointer to a specific commit. Labels play the same role as Git branches and tags, collapsed into a single marker because the BSR is designed to live alongside a VCS rather than replace it.

A commit is referenced by appending its ID to the module name, and a label is referenced by appending the label name:

text
buf.build/bufbuild/protovalidate:d39267d9df8f4053bbac6b956a23169f
buf.build/bufbuild/protovalidate:main

See Referencing a module for where these references show up and the other forms you can use.

Commits ​

Each commit bundles the schema files, Markdown docs, dependency manifest, Buf configuration, and an optional backlink URL to the VCS commit that produced it. A digest of those contents is computed and stored alongside the commit ID.

Commits have no parentage on the BSR. Two commits can be diffed against each other, but there’s no ancestry graph; history lives in a label’s list of commits, not in the commits themselves.

Other properties worth knowing about:

  • Commits are never deleted.
  • A commit always belongs to at least one label. If buf push doesn’t specify one, the commit goes to the default label.
  • The same commit can sit on multiple labels at once.
  • Two pushes with identical content produce the same digest. The BSR deduplicates them into a single commit; no duplicate is created.
  • Any commit can be resolved as a dependency, whether it’s the current head of a label or an older entry in a label’s history.
  • The same logical change can appear as different BSR commits if the content is identical but the backlinked VCS commit differs. That’s how PR review context and commit discussions stay attached across rebases and retries.

A commit’s VCS URL isn’t inferred automatically. buf push only records it when the caller provides it, either with --source-control-url or by passing --git-metadata to have the CLI read it from the local repository state. Buf’s GitHub Action sets this for you.

Labels ​

A label is a mutable pointer to a commit plus the append-only history of every commit it has ever pointed to. Each repository ships with one label named main, which acts as its default label.

Labels usually get applied from CI, wired up so that a push to a VCS branch or a tag produces a BSR push with the corresponding label. You can also pass --label to buf push directly if you want to label a commit from the command line.

When a push targets an existing label, the head advances to the new commit and the previous head slides into the label’s history. If the new commit has the same digest as the current head, the push is a no-op; no new commit is created.

Archiving labels ​

Labels can’t be deleted. Because generated SDKs resolve label names from package managers, deleting a label would break downstream builds in ways a VCS branch deletion never does. Archiving takes its place.

Archiving hides a label from most BSR UI lists (autocomplete, dropdowns) without removing it. Behavior to keep in mind:

  • Archived labels are still valid references and resolve as dependencies.
  • Direct URLs to archived labels still work.
  • Pushing a new commit to an archived label automatically unarchives it.
  • You can unarchive manually from the BSR UI.
  • Buf’s GitHub Action archives labels tied to PR branches when the PR is closed or merged.
  • The default label can’t be archived.

See Pushing to the BSR for the commands to apply, archive, and unarchive labels.