Skip to content

Policies#

Policies are YAML files defining sets of lint and breaking change rules you can share across workspaces. Use policies to ensure all your Protobuf modules meet the same organizational standards and best practices.

Write a policy once in a file like buf.policy.yaml, then reference it from any workspace's buf.yaml. When you run buf lint or buf breaking, its rules are enforced. You can also upload policies to the BSR for central enforcement.

Policies require Buf CLI version 1.57.1 or later.

Example policy#

Policy files define rules and plugins applied to your Protobuf schemas. They may contain a subset of the Buf configuration file: the lint, breaking, and plugins keys. See the buf.policy.yaml reference for more.

Example:

buf.policy.yaml
version: v2
# The default lint configuration for any modules that don't have a specific lint configuration.
#
# If this section isn't present, AND a module doesn't have a specific lint configuration, the default
# lint configuration is used for the module.
lint:
  use:
    - STANDARD
    - TIMESTAMP_SUFFIX # This rule comes from the plugin example below.
# Default breaking configuration. It behaves the same as the default lint configuration.
breaking:
  use:
    - FILE
# Optional Buf plugins. Can use to require custom lint or breaking change rules specified in a locally
# installed Buf plugin. Each Buf plugin is listed separately, and can include options if the plugin allows
# for them. Rules with the `default` value set to true will be checked when 'lint' or 'breaking' are empty.
# To disable the builtin rules set `disable_builtin` to false.
#
# See the example at https://github.com/bufbuild/bufplugin-go/blob/main/check/internal/example/cmd/buf-plugin-timestamp-suffix/main.go
# for more detail about the sample below.
plugins:
  # This specifies the installed plugin to use.
  - plugin: plugin-timestamp-suffix # Specifies the installed plugin to use
    options:
      # The TIMESTAMP_SUFFIX rule specified above allows the user to change the suffix by providing a
      # new value here.
      timestamp_suffix: _time

To use a policy file, reference it from your buf.yaml. More than one can be specified, each with a relative path.

Reference policy files from buf.yaml
version: v2
policies:
  - policy: buf.policy.yaml
  # Multiple policies are allowed, and paths are relative.
  # - policy: ../common/common.policy.yaml

When you run buf lint or buf breaking, the Buf CLI applies the policies defined in your buf.yaml file.

Policy files function the same as buf.yaml configuration files:

  • Setting disable_builtin to true for lint or breaking disables Buf's built-in rules.
  • The plugins section allows you to include custom rules and categories. See Buf check plugins for more.

Uploading policies to BSR#

Enterprise users can upload policies to the BSR to share them across modules or enforce them automatically.

Prepare policy files#

Before uploading a policy:

  1. Add a name key in the format buf.build/ORGANIZATION/POLICY_NAME, where buf.build is the hostname of your BSR.
  2. Update the names of any custom plugins to their remote plugin names.
buf.policy.yaml suitable for uploading to a BSR
 version: v2
+name: buf.build/acme/timestamp-policy
 lint:
   use:
     - STANDARD
     - TIMESTAMP_SUFFIX
 breaking:
   use:
     - FILE
 plugins:
-  - plugin: plugin-timestamp-suffix
+  - plugin: buf.build/acme/plugin-timestamp-suffix
     options:
       timestamp_suffix: _time

Using custom plugins#

Policies uploaded to the BSR may only reference Buf plugins that are already published to the BSR, ensuring that other developers can use the policy without needing to install its plugin locally. To publish a Buf plugin, see the Publishing a plugin guide.

Push policies to the BSR#

To push the policy to the BSR, use the buf policy push command. For new policies, include the --create and --create-visibility flags to create the policy and set its visibility:

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

Use remote policies#

Use a remote policy by first updating your buf.yaml file to reference it by name:

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

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

$ buf policy update

When you run buf lint or buf breaking, the Buf CLI downloads and applies the remote policy to your Protobuf schemas.

BSR policy enforcement#

Enterprise users can enforce uploaded policies globally, per-organization, or per-repository, ensuring your Protobuf follows organizational standards and best practices. When configured, each commit within the specified targets is checked against the policy. If a commit doesn't conform to the policy, the system:

  • Outputs errors with detailed information (file path, line/column, error type, and message)
  • Triggers the BSR review flow for manual resolution
  • Blocks labels from resolving to the commit until errors are resolved or approved

Configuring enforcement#

To configure enforcement:

  1. Navigate to the scope for your policy (BSR instance admin panel, Organization settings, or Repository settings).
    • Use the instance scopes for company-wide standards
    • Use organizations for team-specific rules
    • Use repositories for project-specific requirements
  2. Go to Policy Enforcement settings
  3. Click Create Enforcement
  4. Select your uploaded policy (optionally selecting a specific reference)
  5. Define a target. Targets use glob patterns to match within your scope:
    • *: Match all
    • main: Match any with the exact "main" name
    • release-*: Match any with the prefix "release-"
  6. Save the configuration

Once created, the BSR checks new commits in the default label of the repositories that match your target criteria.

Modifying enforcement#

Return to the scope of the Policy Enforcement you want to update (BSR instance admin panel, Organization settings, or Repository settings). Select the configuration to modify, update the policy or targets as needed, and save your changes.

When commits fail policy checks#

When a commit fails policy checks:

  1. Review: Check the error details in the BSR or CLI output
  2. Fix: Update your Protobuf files to address the errors
  3. Push: Commit and push your changes
  4. Monitor: Verify the commit passes checks in the BSR

Because policies are additive, a single module may need to satisfy multiple policies from different scopes.