buf.policy.yaml v2 config file

The buf.policy.yaml file is used to define policies for your modules. It is a subset of the Buf configuration file containing only its lint, breaking, and plugins sections. The buf.policy.yaml file is versioned, and the current version is v2.

Annotated buf.policy.yaml configuration

version: v2
name: buf.build/acme/bar-policy
# The default lint configuration. Applies to all modules with this policy applied.
lint:
  use:
    - STANDARD
    - RPC_SUFFIX # This rule comes from a custom Buf plugin.
  except:
    - IMPORT_USED
  enum_zero_value_suffix: _UNSPECIFIED
  rpc_allow_same_request_response: false
  rpc_allow_google_protobuf_empty_requests: false
  rpc_allow_google_protobuf_empty_responses: false
  service_suffix: Service
  disable_builtin: false
# Default breaking configuration. It behaves the same as the default lint configuration.
breaking:
  use:
    - FILE
  except:
    - EXTENSION_MESSAGE_NO_DELETE
  ignore_unstable_packages: true
  disable_builtin: false
# 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.
plugins:
  - plugin: buf.build/acme/buf-check-plugin # Specifies the plugin to use
    options:
      # Options for the Buf check plugin can be specified here.
      rpc_suffix: "MustBeThisSuffix"

version

Required. Defines the current configuration version. The only accepted values are v2.

name

Optional. A Buf Schema Registry (BSR) path that uniquely identifies this policy. The name must be a valid policy name and it defines the BSR repository that contains the commit and label history for the policy configuration.

lint

Optional. The lint settings you specify in this section are the default for all modules in the workspace, but can be replaced for individual modules by specifying different settings at the module level. Module-level settings have all of the same fields and behavior as workspace-level settings. If no lint settings are specified for the workspace, it uses the default settings.

use

Optional. Lists the categories and/or specific rules to use. For example, this config selects the BASIC lint category and the FILE_LOWER_SNAKE_CASE rule:

buf.yaml – Lint basic usage

version: v2
lint:
  use:
    - BASIC
    - FILE_LOWER_SNAKE_CASE

The STANDARD category is used if lint is unset.

except

Optional. Omits rules or categories from the use list. For example, this config enforces all lint rules in the STANDARD lint category except for ENUM_NO_ALLOW_ALIAS and all rules in the BASIC category:

buf.yaml – Exclude rules or categories from the initial lint setting

version: v2
lint:
  use:
    - STANDARD
  except:
    - ENUM_NO_ALLOW_ALIAS
    - BASIC

Note that since STANDARD is the default value for use, this is equivalent to the above:

buf.yaml

version: v2
lint:
  except:
    - ENUM_NO_ALLOW_ALIAS
    - BASIC

enum_zero_value_suffix

Optional. Controls the behavior of the ENUM_ZERO_VALUE_SUFFIX lint rule. By default, this rule verifies that the zero value of all enums ends in _UNSPECIFIED, as recommended by the Google Protobuf Style Guide. However, organizations can choose a different preferred suffix — for example, _NONE. To set it, provide the desired value:

buf.yaml – Change default suffix

version: v2
lint:
  enum_zero_value_suffix: _NONE

That config allows this:

enum Foo {
  FOO_NONE = 0;
}

rpc_allow_same_request_response

Optional. Allows the same message type to be used for a single RPC's request and response type. We don't recommend using this option.

rpc_allow_google_protobuf_empty_requests

Optional. Allows RPC requests to be google.protobuf.Empty messages. You can set this if you want to allow messages to be void forever and never take any parameters. We don't recommend using this option.

rpc_allow_google_protobuf_empty_responses

Optional. Allows RPC responses to be google.protobuf.Empty messages. You can set this if you want to allow messages to never return any parameters. We don't recommend using this option.

service_suffix

Optional. Controls the behavior of the SERVICE_SUFFIX lint rule. By default, this rule verifies that all service names are suffixed with Service. However, organizations can choose a different preferred suffix — for example, API. To set that:

buf.yaml – Change suffix to 'API'

version: v2
lint:
  service_suffix: API

That config allows this:

service FooAPI {}

disable_builtin

Optional. Default is false if unset. If this option is set to true, Buf's built-in lint rules are disabled.

breaking

Optional. Specifies the breaking change detection rules enforced on the Protobuf files in the directory.

use

Optional. Lists the rules or categories to use for breaking change detection. For example, this config selects the WIRE category and the FILE_NO_DELETE rule:

buf.yaml - Breaking changes detection basic usage

version: v2
breaking:
  use:
    - WIRE
    - FILE_NO_DELETE

The FILE category is used if breaking is unset, which is conservative and appropriate for most teams.

except

Optional. Removes rules or categories from the use list. For example, this config results in all breaking rules in the FILE category being used except for FILE_NO_DELETE:

buf.yaml – Exclude rules or categories from the initial breaking change detection setting

version: v2
breaking:
  use:
    - FILE
  except:
    - FILE_NO_DELETE

We don't recommend using this option.

ignore_unstable_packages

Optional. Ignores packages with a last component that's one of the unstable forms recognized by the Buf checker's PACKAGE_VERSION_SUFFIX rule:

• v\d+test.*
• v\d+(alpha|beta)\d*
• v\d+p\d+(alpha|beta)\d*

For example, if this option is set, these packages are ignored:

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

disable_builtin

Optional. Default is false if unset. If this option is set to true, Buf's built-in breaking rules are disabled.

plugins

Optional. Specifies Buf plugins for applying custom lint or breaking change rules and categories, either in place of or in addition to Buf's. This field lists the plugins to use and their options, and you then specify their rules and categories in the lint and/or breaking sections where you want them to be checked.

plugin

Required. A string that points to a Buf plugin binary on your ${PATH}, its relative or absolute location on disk, or a remote BSR plugin path. Alternatively, you can specify a list of strings, with the remaining strings being arguments passed to the plugin binary.

options

A list of option definitions if the plugin allows for them. These are key-value pairs, and are usually used to overwrite a default value (for example, a field suffix), and then run the check against the new value instead. See the bufplugin Wasm example example for more details.