Policy enforcement – Overview

Policy enforcement ensures all of your Protobuf modules meet organizational standards and follow best practices. Policies allow you to define a set of rules to share between multiple workspaces, ensuring consistency and quality across your projects. They can be applied locally in conjunction with buf lint and buf breaking, and enforced centrally by the BSR.

Key concepts

Policy: A YAML file encapsulating a set of lint and breaking change rules, along with any necessary Buf plugins. Policies are built on top of Buf's built-in lint and breaking change rules. Custom rules can be implemented using Buf plugins to augment the built-in rules.

Enforcement: The application of a policy to a specific scope (BSR instance, organization, or repository) and targets (glob rules that match organization and modules within the scope). When policy enforcement is enabled, each commit in the default label within the targets is checked against the policy to determine conformance.

Violation: Output generated when a local buf breaking/buf lint run or a BSR commit fails an enforcement. Violations include the file path, line/column information, error type, error message, and relevant Buf plugin and policy names.

Buf plugins: Plugins that define lint and breaking change rules for use within policies. These allow you to create custom rules and categories. Buf's built-in rules are implemented as Buf plugins. Unlike remote protoc plugins (which generate code), Buf plugins must be compiled to WebAssembly (WASM) for upload to the BSR.

To get started with policies, you can follow the quickstart guide to create a policy from scratch. Then, upload the policy to share and use it within the BSR with policy enforcement.