Skip to content

Plugin version constraints#

A plugin version constraint limits which versions of a specific plugin can be used to generate SDKs for a single BSR repository. Constraints are set per repository by users with the Admin role on that repository. Use them to keep consumers off plugin versions with known bugs, breaking changes, or security issues.

What constraints affect#

Constraints apply to BSR-hosted Generated SDKs only. Every supported registry honors them, including Go, npm, Maven, Python, Cargo, NuGet, Swift, and CMake. They don’t affect buf generate invocations that fetch remote plugins directly.

Two consequences for consumers of a constrained repository:

  • latest resolution in any package manager that talks to the BSR returns the newest plugin version that satisfies every constraint.
  • SDK versions that don’t satisfy the constraints stop resolving and return 404 to consumers, even if those SDKs were published before the constraint was added.

Add a constraint#

  1. Navigate to your repository in the BSR and click the Settings icon at top-right.
  2. Scroll to the Manage available plugin versions section.
  3. Click Add plugin constraint.
  4. Search for and select the plugin to constrain.
  5. Choose an operator and version (see Operators below).
  6. Add more operator-version pairs to refine the rule. Multiple conditions on the same plugin are combined with logical AND.
  7. Click Save constraint.

Operators#

Operator Meaning Example
== Equal to == 2.5.1
!= Not equal to != 1.4.2
> Greater than > 1.0.0
>= Greater than or equal to >= 2.1.0
< Less than < 3.0.0
<= Less than or equal to <= 2.9.99

Combine constraints#

To pin a plugin to the 2.x line excluding a known-bad release, set three rules on the same plugin:

  • >= 2.1.0
  • < 3.0.0
  • != 2.4.7

Saved together, these are combined with logical AND: only plugin versions in [2.1.0, 3.0.0) and not equal to 2.4.7 are eligible to generate SDKs for the repository. Consumers requesting latest see the newest plugin version that satisfies all three; consumers requesting 2.4.7 directly get a 404.