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 tutorial 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>
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:
repositories {
mavenCentral()
maven {
url = uri("https://buf.build/gen/maven")
}
}
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:
repositories {
mavenCentral()
maven {
url "https://buf.build/gen/maven"
}
}
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")
}
}
}
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.):
bufName=Authorization
bufValue=Bearer {token}
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)
}
}
}
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.):
bufName=Authorization
bufValue=Bearer {token}
Names and versions
The BSR Maven repository has a special syntax for SDK names:
{moduleOwner}_{moduleName}_{pluginOwner}_{pluginName}
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
:
{moduleOwner}_{moduleName}_{pluginOwner}_{pluginName}_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 .
:
{sdkName}:{pluginVersion}.{pluginRevision}.{commitTimestamp}.{commitShortName}
As an example:
connectrpc_eliza_connectrpc_kotlin:0.3.0.2.20230913231627.233fca715f49
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.
Related docs
- Try the generated SDKs tutorial to learn how to generate SDKs from the BSR.