Skip to content

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>:

pom.xml
  <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:

pom.xml
<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:

build.gradle.kts
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:

build.gradle.kts
{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:

build.gradle
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:

build.gradle
{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:

~/.m2/settings.xml
<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:

build.gradle.kts
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.):

~/.gradle/gradle.properties
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:

build.gradle
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.):

~/.gradle/gradle.properties
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.

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.