Deprecated

Federation

ProEnterprise

DEPRECATED

We recommend using the default managed modules feature, which synchronizes the community modules hosted in the public BSR to your private BSR server.

Federation is the ability for Buf modules to have a dependencies on a module hosted on different BSR server. For example, a module on buf.example.com may depend on a public BSR module like buf.build/googleapis/googleapis. Although hosted on a different remote, federated dependencies work the same as regular dependencies.

Use of Federation creates a dependency between your single-tenant instance and buf.build. For this reason federation is turned off by default for new customers. If you wish to use this feature, please reach out to a Buf representative.

Limitations

Depending on a module from buf.build does not automatically mirror this module into your BSR.

Federation is currently only supported between enterprise instances (for instance buf.example.com) and public buf.build modules. See the table below for an overview:

Module	Dependency	Supported
`buf.example.com/foo/bar`	`buf.build/user/public-repository`	Yes
`buf.example.com/foo/bar`	`buf.build/user/private-repository`	No (dependencies on private modules not supported)
`buf.example.com/foo/bar`	`different-buf.example.org/user/repository`	No (dependencies between enterprise BSRs not supported)
`buf.build/foo/bar`	`buf.example.com/user/public-repository`	No (federation is a enterprise-only feature)

Migration

The easiest way to move away from federated modules is to depend on a local copy. The BSR automatically synchronizes a list of well-known community modules using the managed modules feature.

Manual upload

If the module that you want to sync can't be added to the managed modules repository, then you can manually upload a copy to your instance:

Export the module from buf.build to a local directory.
Initialize a new local module under the buf.example.com private instance.
Create the organization and repository.
Push the module.

Example sequence

$ buf export buf.build/acme/petapis --output petapis
$ cd petapis
$ buf mod init buf.example.com/acme/petapis
$ buf beta registry organization create buf.example.com/acme
$ buf beta registry repository create buf.example.com/acme/petapis --visibility public
$ buf push