Breaking change check#

This feature is only available on the Enterprise plan.

Buf's breaking change check allows you to enforce the Buf CLI's breaking change rules across your entire private BSR instance with minimal configuration. This page describes how the breaking change check works and how to enable and disable it on your private BSR instance. You must be a BSR administrator to access these settings.

This check is not enabled by default.

How it works#

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

Once enabled, the breaking change check is enforced for all modules in the BSR. Non-compliant schemas enter into a review flow, where owners can approve or reject them. These settings take precedence over any breaking change configuration specified in a given workspace's buf.yaml file, and work even if buf.yaml disables the breaking change configuration completely.

Enabling the breaking change check#

To enable instance-wide breaking change prevention on your BSR instance:

Go to the admin panel and select Checks in the Settings section of the menu.
In the Breaking change prevention section, turn the Enforce breaking change prevention toggle on.
Select the strictness level of breaking changes you want to enforce: FILE or WIRE_JSON.
To ignore breaking changes in unstable packages, click the Unstable packages toggle.
Click Update to save your settings.

Ignoring 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

Disabling the breaking change check#

Resolve pending commits#

If your organization decides to disable this feature, we require that all pending commits be approved or rejected beforehand, preventing "dangling" pending commits. To make this easy, we've added bulk approve and reject functionality to the BSR admin panel. From the admin panel, BSR admins can see all of the repositories with commits still in review. They can choose to bulk approve or reject remaining commits, or click into the repository itself to review the remaining commits more carefully.

Disable the check#

When no commits are left pending on the instance, the breaking change check can be disabled from the admin panel:

Go to the admin panel and select Checks in the Settings section of the menu.
In the Breaking change prevention section, turn the Enforce breaking change prevention toggle off.
Click Update to save your settings.

After disabling the breaking change check, any already-rejected commits are still unavailable to downstream consumers.

Interaction with local breaking change configurations#

When the breaking change check is enabled, local setups and CI configurations continue to work, and the instance-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, instance-wide rules configured in the BSR always take precedence over local rules.

You can see the instance-wide setting that's applied for your organization by clicking the Rules tab in any module in the BSR.