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:
-
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
. -
Click the Prevent breaking changes toggle.
-
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 thebuf.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 haveWIRE_JSON
locally andFILE
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.
- The Buf CLI shows a warning if the breaking change configuration in the local