Skip to content

Set up a Pro or Enterprise BSR instance#

This page covers Buf-hosted private BSR instances on Pro and Enterprise plans. For self-hosted deployments, see On-premise deployment with Kubernetes.

Buf-hosted private BSR instances come in two shapes:

  • Pro: Buf hosts the instance at a Buf-assigned subdomain of the form NAME.buf.dev, where NAME is your BSR organization name.
  • Enterprise: Buf hosts the instance behind a custom domain you own (for example, buf.example.com), with the option of additional networking controls.

Both shapes are reachable from the public internet and authenticated by SSO and CLI tokens.

Before you start#

  • Buf has provisioned the instance for you ahead of this page. If that hasn’t happened yet, contact Support or your Buf representative.
  • Complete the sections below in order: configure DNS, promote an initial admin, then connect your identity provider. The order matters because the SSO switch-over matches sign-in attempts to existing accounts by email, so an admin account must exist on the instance before SSO is enabled.

Configure DNS#

No additional DNS setup is required. Reference the Buf-assigned NAME.buf.dev host (instead of the public BSR at buf.build) when running buf commands, creating modules, or referencing modules as dependencies.

Choose the domain you’ll use for the instance and share it with Support or your Buf representative. A Buf engineer responds with the value to use in your CNAME records.

The example below uses example-corp.enterprise.buf.build as a placeholder for that value:

buf.example.com.          CNAME    example-corp.enterprise.buf.build.

For additional networking controls such as IP-range restriction, contact Support or your Buf representative.

Promote an initial admin#

A private BSR instance grants extra capabilities to administrator accounts (instance configuration, user lifecycle management, plugin management). At least one user has to be promoted to registry admin before SSO is enabled. For instructions, see Provisioning admin users.

Connect your identity provider#

By default, a freshly provisioned BSR instance authenticates against the public BSR. To switch authentication to your own identity provider, follow the setup guide for your provider:

For the user provisioning model behind these flows, see User lifecycle. Have users sign up with their organization email address before the SSO switch-over so the BSR can merge their existing accounts to the SSO identities automatically.

How sign-in matches existing accounts#

When a user signs in via SSO for the first time, the BSR matches them to an existing account by the email address provided by the IdP. A match links the SSO identity to the existing account and preserves the user’s history and permissions. A miss provisions a new account.

GitHub primary email

For GitHub OAuth2, the BSR matches against the user’s GitHub primary email address. Have users set their primary GitHub email to their organization address before signing in for the first time, otherwise the BSR provisions a new account instead of linking to the existing one.

Next steps#

  • User lifecycle: how the BSR provisions, promotes, and deactivates users.
  • SCIM: sync users and groups directly from your IdP.
  • Manage organizations: create organizations, manage members, and assign roles on the instance.
  • Resource visibility: set the default privacy posture for repositories, plugins, and policies.