Skip to content

Maven and Gradle#

The BSR exposes a Maven repository at https://buf.build/gen/maven for BSR-generated Java and Kotlin SDKs. Any tool that speaks Maven (mvn, Gradle, IntelliJ, Android Studio) can resolve from it.

A first dependency:

build.gradle.kts
implementation("build.buf.gen:connectrpc_eliza_connectrpc_kotlin:0.8.0.1.20230913231627.233fca715f49")

For an end-to-end walkthrough, see the generated SDKs quickstart.

SDK coordinates#

A BSR-generated SDK has three coordinates:

Coordinate Format Example
groupId Tied to the BSR host. On buf.build, always build.buf.gen. build.buf.gen
artifactId {moduleOwner}_{moduleName}_{pluginOwner}_{pluginName} connectrpc_eliza_connectrpc_kotlin
version See Versions below. 0.8.0.1.20230913231627.233fca715f49

Private BSR instances use a groupId derived from the instance host; on-prem operators can customize it (see Maven registry groupId).

Plugins that support the Java Protobuf Lite runtime expose a parallel _lite artifact:

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

Installing the _lite variant generates code with Lite-runtime dependencies, which fits Android targets. Not every plugin offers a Lite variant; the SDK page on the BSR shows it when available.

Add the BSR Maven repository#

Add the repository to pom.xml:

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>

The <id>buf</id> value matters: for private SDKs, it has to match the <id> in the <server> block of ~/.m2/settings.xml (see Authenticate for private SDKs).

Add the repository to build.gradle.kts:

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

The name = "buf" value matters: for private SDKs, Gradle prefixes header-credential property names with this value (see Authenticate for private SDKs).

Add the repository to build.gradle:

build.gradle
repositories {
  mavenCentral()
  maven {
    name = 'buf'
    url = 'https://buf.build/gen/maven'
  }
}

The name = 'buf' value matters: for private SDKs, Gradle prefixes header-credential property names with this value (see Authenticate for private SDKs).

Add a dependency#

pom.xml
<dependencies>
  <dependency>
    <groupId>build.buf.gen</groupId>
    <artifactId>connectrpc_eliza_connectrpc_kotlin</artifactId>
    <version>0.8.0.1.20230913231627.233fca715f49</version>
  </dependency>
</dependencies>
build.gradle.kts
dependencies {
  implementation("build.buf.gen:connectrpc_eliza_connectrpc_kotlin:0.8.0.1.20230913231627.233fca715f49")
}
build.gradle
dependencies {
  implementation 'build.buf.gen:connectrpc_eliza_connectrpc_kotlin:0.8.0.1.20230913231627.233fca715f49'
}

Authenticate for private SDKs#

For SDKs generated from private BSR repositories, supply a personal API token for local development or a bot user token for CI. For token setup, see Authentication.

Add a <server> entry to ~/.m2/settings.xml. The <id> has to match the repository <id> in pom.xml (buf in this guide):

~/.m2/settings.xml
<settings>
  <servers>
    <server>
      <id>buf</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer {token}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

Configure HttpHeaderCredentials and HttpHeaderAuthentication on the repository. The repository name ("buf") prefixes the credential property names so Gradle resolves them from ~/.gradle/gradle.properties:

build.gradle.kts
repositories {
  mavenCentral()
  maven {
    name = "buf"
    url = uri("https://buf.build/gen/maven")
    credentials(HttpHeaderCredentials::class)
    authentication {
      create<HttpHeaderAuthentication>("header")
    }
  }
}

Set the credentials in ~/.gradle/gradle.properties (or any other Gradle configuration property mechanism):

~/.gradle/gradle.properties
bufName=Authorization
bufValue=Bearer {token}

Configure HttpHeaderCredentials and HttpHeaderAuthentication on the repository. The repository name ('buf') prefixes the credential property names so Gradle resolves them from ~/.gradle/gradle.properties:

build.gradle
repositories {
  mavenCentral()
  maven {
    name = 'buf'
    url = 'https://buf.build/gen/maven'
    credentials(HttpHeaderCredentials)
    authentication {
      header(HttpHeaderAuthentication)
    }
  }
}

Set the credentials in ~/.gradle/gradle.properties (or any other Gradle configuration property mechanism):

~/.gradle/gradle.properties
bufName=Authorization
bufValue=Bearer {token}

Versions#

A BSR Maven version concatenates the plugin version, plugin revision, and module commit:

Version syntax
{pluginVersion}.{pluginRevision}.{commitTimestamp}.{commitShortName}

# Example
0.8.0.1.20230913231627.233fca715f49
Part Example Source
Plugin version 0.8.0 The plugin’s own version.
Plugin revision 1 BSR-side rebuild count for that plugin version.
Commit timestamp 20230913231627 Module commit timestamp (YYYYMMDDHHMMSS).
Commit short name 233fca715f49 First 12 characters of the module commit ID.

Commits pushed to non-default labels carry 00000000000000 as the timestamp so they sort below released versions. The BSR supports commits on labels for non-default labels.

To pin a specific plugin version (rather than the latest plugin against a chosen module ref), use the buf registry sdk version CLI command.

Available plugins#

The full list of supported Java and Kotlin plugins lives on the BSR plugins page (filter for Java or Kotlin). For how those plugins are packaged, see the bufbuild/plugins repository; to request a new plugin, file an issue.

Troubleshooting#

Generated Java code fails to compile because of a Java reserved keyword#

If a Protobuf field uses a Java reserved keyword (public, native, and similar), the generated Java code won’t compile, regardless of whether the code was generated locally or by the BSR. Avoid Java reserved keywords as field names in modules that produce Java SDKs.

Can BSR Maven JARs be hosted without the build.buf.gen prefix?#

The package prefix is tied to the BSR host name and isn’t configurable on buf.build. Private BSR instances use a different default prefix derived from their host name. On-prem operators can customize the groupId prefix; see Maven registry groupId.