Maven/Gradle
The Buf Schema Registry provides generated SDKs for JVM-based languages in the form of a Maven repository, just like any other Java or Kotlin library. It generates SDKs automatically when you push schema changes, which eliminates the need to manage a Protobuf toolchain or generate code locally.
The BSR's Maven repository is hosted at https://buf.build/gen/maven. See the quickstart for instructions on how to access generated SDKs from the BSR directly.
Setup and usage
Follow the instructions for your package manager of choice below.
Setup
Update your pom.xml file to include the Buf Maven repository as a <repository>:
<repositories>
<repository>
<name>Buf Maven Repository</name>
<id>buf</id>
<url>https://buf.build/gen/maven</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
Note
The <id> value is important for using private generated SDKs because it must match the <id> in the <server> section of the ~/.m2/settings.xml file (see the private generated SDKs section for more details).
Adding a dependency
To add a dependency on a generated SDK, add the groupId, artifactId, and version to the <dependencies> section of your pom.xml file:
<dependencies>
<dependency>
<groupId>build.buf.gen</groupId>
<artifactId>connectrpc_eliza_connectrpc_kotlin</artifactId>
<version>0.3.0.2.20230913231627.233fca715f49</version>
</dependency>
</dependencies>
See the names and versions section for syntax specifics.
Setup
Update your build.gradle file to include the Buf Maven repository:
Adding a dependency
To add a dependency on a generated SDK, add the dependency to the dependencies section of your build.gradle.kts file:
{implementation("build.buf.gen:connectrpc_eliza_connectrpc_kotlin:0.3.0.2.20230913231627.233fca715f49")}
See the names and versions section for syntax specifics.
Setup
Update your build.gradle file to include the Buf Maven repository:
Adding a dependency
To add a dependency on a generated SDK, add the dependency to the dependencies section of your build.gradle file:
{implementation("build.buf.gen:connectrpc_eliza_connectrpc_kotlin:0.3.0.2.20230913231627.233fca715f49")}
See the names and versions section for syntax specifics.
Private generated SDKs
When using SDKs generated from private BSR repositories, you'll need to authenticate by including a personal API token for local use or a Bot user's API token for CI workflows. See the Authentication page for instructions.
To use private generated SDKs with Maven, edit your ~/.m2/settings.xml file to include your API token:
<settings>
<servers>
<!--
Add this <server>, replacing {token} with your API Token.
The <id> value must match the id of the Buf Maven repository in your
pom.xml file - in this guide, it's `buf`.
-->
<server>
<id>buf</id>
<configuration>
<httpHeaders>
<property>
<name>Authorization</name>
<value>Bearer {token}</value>
</property>
</httpHeaders>
</configuration>
</server>
</servers>
</settings>
To use private generated SDKs with Gradle, specify your repository with an HttpHeaderCredentials property, specify that you're using HttpHeaderAuthentication, and then specify your actual header credentials as Gradle properties, so that your API token is kept secret:
repositories {
mavenCentral()
maven {
name = "buf"
url = uri("https://buf.build/gen/maven")
credentials(HttpHeaderCredentials::class)
authentication {
create<HttpHeaderAuthentication>("header")
}
}
}
Note
The name value is important for using private generated SDKs because it must be prefixed to each Gradle property that makes up the header credentials.
To specify the actual header credentials as Gradle properties, you can set them in your ~/.gradle/gradle.properties file, or in any other way that Gradle allows Gradle properties to be specified (command-line, environment variables, etc.):
To use private generated SDKs with Gradle, specify your repository with an HttpHeaderCredentials property, specify that you're using HttpHeaderAuthentication, and then specify your actual header credentials as Gradle properties, so that your API token is kept secret:
repositories {
mavenCentral()
maven {
name = 'buf'
url = 'https://buf.build/gen/maven'
credentials(HttpHeaderCredentials)
authentication {
header(HttpHeaderAuthentication)
}
}
}
Note
The name value is important for using private generated SDKs because it must be prefixed to each Gradle property that makes up the header credentials.
To specify the actual header credentials as Gradle properties, you can set them in your ~/.gradle/gradle.properties file, or in any other way that Gradle allows Gradle properties to be specified (command-line, environment variables, etc.):
Names and versions
The BSR Maven repository has a special syntax for SDK names:
For example, the SDK name connectrpc_eliza_connectrpc_kotlin contains code for the connectrpc/eliza module using the connectrpc/kotlin plugin.
Additionally, if a plugin supports the Java Protobuf Lite runtime, the name is suffixed with _lite:
When installing the connectrpc_eliza_connectrpc_kotlin_lite SDK, the BSR generates code for the connectrpc/eliza module using the connectrpc/kotlin plugin, ensuring that dependencies are using the lite runtime, which makes the SDK suitable for use on Android.
Versions
To discover SDK versions for the Maven repository, you can browse a repository's SDK page, which has installation instructions and an interactive UI.
Full syntax
The version, revision, and commit information for plugins is appended to the SDK name described above with a preceding colon, with each field separated by .:
As an example:
That represents:
- Plugin version:
0.3.0 - Plugin revision:
2 - Commit timestamp:
20230913231627 - Commit short name:
233fca715f49
If you need a more specific version than the latest, such as needing to install a specific plugin version, you can use the buf registry sdk version command.
The BSR supports commits on labels. This feature enables you to push unreleased Protobuf file changes and consume generated code without affecting the default label.
Only commits that are on the default label at the time they're pushed to the BSR have populated timestamps.
Timestamps on commits pushed to other labels are zeroed out with 00000000000000 to easily distinguish them as changes in labels that are still in development.
Available plugins
For a full list of supported plugins, navigate to the BSR plugins page and search for Java or Kotlin.
To learn more about how these plugins are packaged and distributed, go to the bufbuild/plugins repository. If you find a useful plugin that should be added, file an issue.
Troubleshooting
Why does generating Java code using my valid module as an input result in an error?
Some users' Protobuf packages may use Java reserved keywords (public, native, etc.).
The generated code fails to compile if it includes one of these keywords, regardless of whether it's generated by a plugin
locally or remotely.
We suggest avoiding the use of Java reserved keywords in modules that you expect to use for generating code.
Can Maven JARs be hosted without the build.buf.gen prefix?
No. The package name prefix is tied to the host name of the BSR, so it can't be changed or removed. Private BSR instances for Pro, Enterprise, and On-prem plans have a different prefix based on their host name.