Skip to content

buf.policy.yaml v2 config file#

The buf.policy.yaml defines a policy. It's a subset of the Buf configuration file containing only its lint, breaking, and plugins sections.

The buf.policy.yaml config file and field definitions below explain usage for each field. See the lint and breaking change detection overviews for default configurations for those features.

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
  # To disable the built-in rules, set `disable_builtin` to false.
  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
  # To disable the built-in rules, set `disable_builtin` to false.
  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.
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 for more details.