Policies quickstart

This quickstart guide will help you create a policy from scratch. We will cover the following topics:

• Policy configuration file
• Using policies

Prerequisites

• Install the Buf CLI or update your existing version to >=1.57.1

Policy configuration file

A policy configuration file defines rules and plugins applied to your Protobuf schemas. It is a subset of the Buf configuration file containing the lint, breaking, and plugins sections.

Create the policy file buf.policy.yaml

Create a new YAML file, like buf.policy.yaml. It will contain the configuration for your policy, including the rules and plugins you want to apply. The version of the policy file should be set to v2, which is the current version of the Buf policy configuration format.

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

A buf.policy.yaml without the lint and breaking sections will apply any default rules for the built-in and plugins. To disable built-in rules, set the disable_builtin: true for either section. Buf plugins can also be specified in the plugins section to include custom rules or categories from Buf plugins.

See the buf.yaml reference for more information about the other keys under lint and breaking.

Using policies

To use policies, you need to configure your buf.yaml file to reference the policy configuration file. You can do this by adding the policies key to your buf.yaml file, like so:

buf.yaml

version: v2
policies:
  - policy: buf.policy.yaml

The policy is a relative path to the policy configuration file, which can be located in the same directory as your buf.yaml file or in a subdirectory. You can also specify multiple policies by adding more entries to the policies list.

When you run buf lint or buf breaking, the Buf CLI automatically applies the policies defined in your buf.yaml file. This means that any rules or plugins defined in the policy configuration file will be applied to your Protobuf schemas.

Now that you have a working policy configuration, you can learn how to publish it to the BSR.