Skip to content

Migrate to a private BSR instance#

A Buf Pro subscription gives your organization a private BSR instance hosted at <org>.buf.dev, where <org> is the BSR organization name. This page is for the org admin running the migration from the public BSR at buf.build to that private instance.

Before you start#

  • Buf has provisioned the Pro instance; you have admin access on it.
  • You know which BSR modules and dependencies in your organization need to move (every published module, plus any internal buf.yaml files that depend on them).
  • For sign-in details on the new instance, see authentication.

Sign in to the new instance#

Run buf registry login against the private hostname:

$ buf registry login <org>.buf.dev

The CLI runs a browser flow and saves the resulting token to .netrc. You can also generate or revoke tokens manually at https://<org>.buf.dev/settings/user.

For non-interactive workloads (CI, scheduled jobs, scripts), generate a bot user and use its token instead of a personal token.

Add members#

The Pro tier supports two ways to provision members on the private instance.

Option 1: Single sign-on#

Configure the private instance to authenticate against your existing identity provider:

Option 2: Use the public BSR as the identity provider#

If you don’t have a separate IdP, the public BSR can stand in. Identity stays on buf.build; the private instance creates a matching local user (and grants the default access) the first time someone signs in.

  1. New members sign up on the public BSR.
  2. The org admin adds them to the public-BSR organization at https://buf.build/<org>/members.
  3. Each new member then signs in to <org>.buf.dev. The first sign-in provisions their account on the private instance.

Granting privileges to specific repositories on the private instance is a separate step, configured through private-instance organizations and teams.

Update modules and dependencies#

The migration boils down to: every module name and dependency that currently points at buf.build must point at <org>.buf.dev instead. Cross-domain dependencies aren’t supported, so the order matters.

  1. Inventory dependencies. List every deps: entry used by the modules you’re moving. Buf-managed modules like googleapis and protoc-gen-validate replicate to the private instance automatically; any other third-party public module has to be mirrored or republished to the private instance before modules that depend on it can move.

  2. Wait for managed modules to sync. Sync usually takes a few hours after the instance is provisioned. Confirm a managed module resolves on the private instance before continuing:

    $ buf build buf.build/googleapis/googleapis  # sanity check on the public BSR
$ buf build <org>.buf.dev/googleapis/googleapis

  3. Push upstream dependency modules first. If your organization has modules that other internal modules depend on, push those dependency modules to <org>.buf.dev before any module that depends on them. This keeps every push resolvable from the new instance.

  4. Rewrite buf.yaml references. In every buf.yaml, replace buf.build with <org>.buf.dev in the name field and in every deps entry that points at one of your own modules. Managed-module deps update the same way.

  5. Push the downstream modules. Run buf push against the updated modules.

Update CI tokens#

Tokens are scoped to a hostname. Replace any buf.build entries in .netrc, BUF_TOKEN environment variables, or CI secrets with <org>.buf.dev equivalents (typically a bot user token on the private instance). For the full token surface, see authentication.

Downgrade: migrate back to the public BSR#

If a Pro subscription ends, the private instance becomes inaccessible after a one-week export window; see the FAQ for the retention policy. Within that window, mirror the migration in reverse:

  1. In every buf.yaml, replace <org>.buf.dev with buf.build in the name field and any internal-module deps entries.
  2. Push the modules to the public BSR.

After the export window closes, the private instance is deleted along with its data.