Maven

The Buf Schema Repository (BSR) provides remote packages for JVM-based languages in the form of a Maven repository. You can consume generated SDKs from modules and plugins using dependency management tools like the Maven CLI and Gradle.

This provides consumers of your API with generated SDKs on demand. With generated SDKs, you no longer need to generate code from Protobuf locally, and thus no longer require consumers to pull in Protobuf files or perform any generation whatsoever.

The BSR's Maven repository is hosted at https://buf.build/gen/maven.

Using private packages

To use private packages with either tool, you need an API token—either an existing API token or a new one. To create a new one, log into the BSR, navigate to your user settings page, and click Create Token.

You can use a Machine user's API token in a similar way, which is useful for authenticating private package access in CI workflows.

See the Maven and Gradle instructions for private packages below.

Maven

Setup

Update your pom.xml file to include the Buf Maven repository as a <repository>, like this:

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

Private packages

To use private packages 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>

Remote packages

To add a dependency on a remote package, add the groupId, artifactId, and version to the <dependencies> section of your pom.xml file. See the remote packages and versions section for syntax specifics.

<dependencies>
  <dependency>
    <groupId>build.buf.gen</groupId>
    <artifactId>bufbuild_eliza_bufbuild_connect-kotlin</artifactId>
    <version>0.1.7.1.20230403200515.aed131420688</version>
  </dependency>
</dependencies>

Gradle

Setup

Update your build.gradle file to include the Buf Maven repository.

repositories {
  mavenCentral()
  maven {
    url = uri("https://buf.build/gen/maven")
  }
}

Private packages

To use private packages 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")
    }
  }
}

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}

Remote packages

To add a dependency on a remote package, add the dependency to the dependencies section of your build.gradle or build.gradle.kts file. See the remote packages and versions section for syntax specifics.

dependencies {
  implementation("build.buf.gen:bufbuild_eliza_bufbuild_connect-kotlin:0.1.7.1.20230403200515.aed131420688")
}

Remote package names and versions

The BSR Maven repository has a special syntax for package names:

{moduleOwner}_{moduleName}_{pluginOwner}_{pluginName}

For example, the package name bufbuild_eliza_bufbuild_connect-kotlin contains code for the bufbuild/eliza module using the bufbuild/connect-kotlin plugin.

Additionally, if a plugin supports the Java Protobuf Lite runtime, the name will be:

{moduleOwner}_{moduleName}_{pluginOwner}_{pluginName}_lite

When installing the bufbuild_eliza_bufbuild_connect-kotlin_lite package, the BSR generates code for the bufbuild/eliza module using the bufbuild/connect-kotlin plugin, ensuring that dependencies are using the lite runtime, which makes the package suitable for use on Android.

Versions

To discover package versions for the Maven repository, you can browse a repository's asset page, which has instructions for installing remote packages and an interactive UI for selecting package versions.

Full syntax

{pluginVersion}.{pluginRevision}.{commitTimestamp}.{commitShortName}

As an example:

0.1.7.1.20230403200515.aed131420688

That is:

• Plugin version: 0.1.7
• Plugin revision: 1
• Commit timestamp: 20230403200515
• Commit short name: aed131420688

For Draft commits, the commit timestamp component of the version is always zeroed out, to easily differentiate package versions using draft commits.

Available plugins

For a full list of supported plugins, navigate to the BSR plugins page and search for Java and 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, please file an issue!