This feature is only available to organizations on the Enterprise plan.

Preventing unintended breaking changes in production is crucial for API and data producers, but often complex to implement across multiple teams. Buf's server-wide breaking change policy enforcement allows you to enforce the Buf CLI's breaking change rules across your entire private BSR server with minimal configuration. And because breaking changes are sometimes necessary, it also provides module owners the ability to review breaking changes before they enter the BSR and then approve or deny them. This allows for nuance in cases where breaking changes are acceptable.

Buf's breaking change policy enforcement:

• Blocks breaking changes from reaching consumers: Commits with breaking changes are put into a "pending" state and aren't released to consumers unless they have been approved.
• Ensures that breaking changes are reviewed by the right team members: Module owners are notified of breaking changes via inbox and email, and can approve or reject the breaking commits via a review flow. All review states and decisions are visible in the BSR, providing a history of schema evolution over time.
• Works regardless of project configuration: Server-wide enforcement supersedes any settings in buf.yaml files or CI, and works even if they aren't present, so enterprises can rely on stable Protobuf contracts.

How it works

Organizations can choose to enforce one of two policies: FILE (the default) or WIRE_JSON.

Once configured, every BSR module will automatically adhere to these rules, and all attempts to push non-compliant schemas will be either be rejected by the server or sent into the review flow, depending on your organization's setup. These settings take precedence over any breaking change configuration specified in a given module's buf.yaml file, and work even if buf.yaml disables the breaking change configuration completely.

Grace period

This allows breaking changes to be pushed to new modules for a short period of time after the module’s intitial creation. It simplifies onboarding for existing Protobuf repositories by allowing old pre-existing breaking changes to be backfilled.

Ignoring in unstable packages

By default, breaking change rules are enforced for all packages, but it's sometimes useful to allow breaking changes in unstable packages. Enabling the Unstable packages setting in the BSR allows breaking changes in any alpha, beta, or test packages. For example:

• foo.bar.v1alpha1
• foo.bar.v1beta1
• foo.bar.v1test

Review flow

Buf's breaking change policy enforcement includes a review flow, so that when developers attempt to push breaking changes to the BSR, commits can be approved or rejected by code owners instead of being rejected outright. This gives downstream consumers protection from breaking schema changes, but allows for nuance in cases where breaking changes are acceptable.

With breaking change enforcement enabled, commits with breaking changes are placed into a review flow with a "pending" state and reviewed by the module's admins. This ensures that the code owners have the opportunity to assess the impact of the breaking changes by viewing the diff, and can make an informed decision about whether to accept them. The Buf CLI outputs a warning message to the committer, and sends an in-app notification and email to the owners notifying them that a commit needs to be reviewed.

Commits that require approval are annotated as such in the repository's Activity tab, and all users see a prominent banner indicating that the repository requires attention.

See Reviewing commits for instructions about how to approve or deny breaking changes.

Effects on downstream consumers

Any commits pushed after a commit that's pending are also set to pending, whether or not those commits are breaking changes. Pending commits are unavailable to downstream consumers while the breaking change awaits review, and rejected commits are always unavailable, as follows:

• They're not available to install from any generated SDK registry, by commit name or tag
  • The "latest" version of a generated SDK is kept at the latest approved or non-reviewed commit
• They're not available to use in Buf Studio
• They're excluded from the Reflection API
• They don't update schemas in the Confluent Schema Registry

Interaction with local breaking change configurations

When breaking change policy enforcement is enabled, local setups and CI configurations continue to work, and the server-wide setting interacts with them in the following ways:

• buf breaking still uses the local configuration in the buf.yaml files. This allows individual teams to be stricter than the organization.
• When running buf push, server-wide rules configured in the BSR always take precedence over local rules.
  • The Buf CLI shows a warning if the breaking change configuration in the local buf.yaml is less strict than what's being enforced by the BSR (for example, if you have WIRE_JSON locally and FILE in the BSR).
  • It also shows a warning if the local buf.yaml specifies excluded files, as exclusions can't be specified in the BSR UI.

You can see the server-wide policy being applied for your organization by clicking the Rules tab in any module in the BSR.

Related docs

• Set up breaking change policy enforcement
• Learn how to review commits
• Browse the breaking change rules and categories