Remote policies

WARNING

This feature is only available on the Enterprise plan.

Uploading policies to the BSR allows you to share them between modules and apply policy enforcement within the BSR. This tutorial will guide you through uploading a policy configuration file to the BSR and using it as a remote policy.

Uploading policies to the BSR

Policies must be uploaded to the BSR to be shared with others. A policy must only use Buf plugins that are already available in the BSR to ensure that other developers can use the policy without needing to install any additional plugins locally. This also allows the BSR to run the policy in a remote environment.

Modify the buf.policy.yaml file to include the name of the policy within an organization, and specify the Buf plugin as a remote plugin. To publish a Buf plugin, see the Publishing a plugin guide. For this example, we will use the organization acme and the Buf plugin plugin-timestamp-suffix.

buf.policy.yaml

 version: v2
name: buf.build/acme/policy-timestamp-suffix
 lint:
   use:
     - STANDARD
     - TIMESTAMP_SUFFIX # This rule comes from the plugin example below.
 breaking:
   use:
     - FILE
 plugins:
  - plugin: plugin-timestamp-suffix
  - plugin: buf.build/acme/plugin-timestamp-suffix
     options:
       timestamp_suffix: _time

To push the policy to the BSR, use the buf policy push command with the --create flag to create the policy if it doesn't already exist and the --create-visibility flag to set the visibility of the policy.

buf policy push buf.policy.yaml --create --create-visibility=public

This command will upload the policy to the BSR and make it publicly available for enforcement.

Using remote policies

To use a remote policy, you need to update your buf.yaml file to reference the remote policy.

buf.yaml

 version: v2
 policies:
  - policy: buf.policy.yaml
  - policy: buf.build/acme/policy-timestamp-suffix

Next, use buf policy update to update the buf.lock file:

$ buf policy update

When you run buf lint or buf breaking, the Buf CLI will automatically download and apply the remote policy to your Protobuf schemas.

Now that you have a remote policy configured, you can use it to enforce the rules defined in the policy across your modules. Check out the Enforcing policies guide for more details on how to set up policy enforcement for your instance, organization, or repository.