This information only applies to organizations on the Pro and Enterprise plans.

Server admins can configure their BSR instances to prevent breaking changes from being pushed to the server. This feature is useful for organizations that want to enforce a set of breaking change rules across all of their repositories in a centralized way.

You 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 rejected by the server. These settings take precedence over any breaking change configuration specified in a given module's buf.yaml file.

Setup

To enable server-wide breaking change prevention across your BSR instance:

1. Go to the Admin panel and select Breaking changes in the Settings section of the menu.

   

   You can access it directly at https://<BSR_SERVER>/admin/breaking-changes.

2. Click the Prevent breaking changes toggle.

3. Select the level of breaking changes you want to enforce: FILE or WIRE_JSON.

Ignoring in unstable packages

By default, breaking change rules will be enforced for all packages, but it's sometimes useful to allow breaking changes in unstable packages. To set this as a policy, click the Unstable packages toggle.

Turning this setting on is the equivalent of setting ignore_unstable_packages on all of your Protobuf modules. It allows breaking changes to be pushed to the following packages in the BSR, for example:

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

Interaction with local buf.yaml configs

When this setting 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 is 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.