Use SDKs with Artifactory

WARNING

This feature is only available on the Pro and Enterprise plans.

The Buf Schema Registry (BSR) provides generated SDKs of generated code through standard registry APIs in each language. This makes it easy to configure artifact management tools like Artifactory to work with the BSR.

This guide uses the buf.example.com BSR instance and https://example.jfrog.io Artifactory instance as examples, but these should be substituted with the domains of your own instances.

Setup

You must be a BSR instance admin to set up Artifactory.

1. First, add a new Go remote repository to your Artifactory instance at https://example.jfrog.io/ui/admin/repositories/remote/new.

   • Set Repository Key to buf-go
   • Set URL to https://buf.example.com/gen/go
   • Open the Advanced tab and check Bypass HEAD Requests

2. In your BSR, create a bot user with a token. Then set the User Name and Access Token of the buf-go repository in Artifactory to the BSR username and token of the bot user that you created.

3. Create a new virtual repository named go, or use an existing virtual Go repository.

   • Edit the virtual repository and add buf-go to the included items under go
   • Ensure that the go-remote remote repository is also added to included items

Usage

Go

1. Click Set Up Client/CI Tool on the go virtual repository and follow the instructions.

2. Run the following in a terminal to configure Artifactory as the go proxy:

   export GOPROXY="https://${ARTIFACTORY_USER}:${ARTIFACTORY_ACCESS_TOKEN}@example.jfrog.io/artifactory/api/go/go"

3. Stop the go client from trying to resolve the sum with the global sumdb, see the GONOSUMDB documentation for more.

   export GONOSUMDB=buf.example.com/gen/go

4. Install modules:

   go get buf.example.com/gen/go/acme/petapis/protocolbuffers/go

NPM

1. Click Set Up Client/CI Tool on the npm virtual repository and follow the instructions.

2. Run the following to configure Artifactory as a global registry, so that all npm install requests are routed to it.

   npm config set registry https://example.jfrog.io/artifactory/api/npm/npm/

   Or, configure only the @bufteam scope used by the BSR.

   npm config set @bufteam:registry https://bufbuild.jfrog.io/artifactory/api/npm/npm/

3. Authenticate with Artifactory:

   npm login

4. Install packages:

   npm install @bufteam/example_hello-service.protocolbuffers_js

Maven

Click Set Up Client/CI Tool on the maven virtual repository and follow the instructions.

For mvn, add the following server to your ~/.m2/settings.xml file, replacing {ArtifactoryUsername} with your Artifactory username, and {ArtifactoryToken} with the token you just generated during setup.

~/.m2/settings.xml

<settings>
  <!-- Other settings -->
  <servers>
    <!-- Add this server! -->
    <server>
      <id>buf-artifactory</id>
      <username>{ArtifactoryUsername}</username>
      <password>{ArtifactoryToken}</password>
    </server>
  </servers>
</settings>

Next, add the repository to your pom.xml file, replacing {ArtifactoryMavenURL} with the URL of your Artifactory Maven Repository:

pom.xml

<repositories>
  <!-- Other repositories -->
  <repository>
    <id>buf-artifactory</id>
    <url>{ArtifactoryMavenURL}</url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>
</repositories>

Then, to use packages add the dependency to your pom.xml file. The easiest way to find dependencies is to go to your module's assets tab on the BSR, which has a listing of versions for your module with all of the plugins on your instance. For example:

pom.xml

<dependencies>
  <!-- ... -->
  <dependency>
    <groupId>com.example.buf.gen</groupId>
    <artifactId>connectrpc_eliza_bufbuild_connect-kotlin</artifactId>
    <version>0.1.8.3.20230727062025.d8fbf2620c60</version>
  </dependency>
</dependencies>

Gradle

For gradle, Artifactory doesn't supply instructions. Add your Artifactory repository to your build.gradle or build.gradle.kts file, and supply your Artifactory username and token as a username and password in Gradle Properties for the repository using credentials.

For example, you could add your credentials to a gradle.properties file in your project, replacing {ArtifactoryUsername} with your Artifactory username, and {ArtifactoryToken} with the token you just generated during setup:

gradle.properties

bufArtifactoryUsername="{ArtifactoryUsername}"
bufArtifactoryPassword="{ArtifactoryToken}"

Then add a repository to your build.gradle or build.gradle.kts file, replacing {ArtifactoryMavenURL} with the URL of your Artifactory Maven Repository.

build.gradle.kts

repositories {
  maven {
    name = "bufArtifactory"
    url = uri("{ArtifactoryMavenURL}")
    credentials(PasswordCredentials::class)
  }
}

To use packages, add the dependency to your build.gradle or build.gradle.kts file. The easiest way to find dependencies is to go to your module's assets tab on the BSR, which has a listing of versions for your module with all of the plugins on your instance.

build.gradle.kts

dependencies {
  implementation("com.example.buf.gen:connectrpc_eliza_bufbuild_connect-kotlin:0.1.8.3.20230727062025.d8fbf2620c60")
}

Python

1. Click Set Up Client/CI Tool on the python virtual repository and follow the instructions. You should end up with an index-url in your ~/.pip/pip.conf file, containing a URL like:

   https://<artifactory-username>:<artifactory-password-or-token>@example.jfrog.io/artifactory/api/pypi/python/simple

2. Install packages:

   pip install example_hello-service_protocolbuffers_python

Cargo

1. Click Set Up Client/CI Tool on the buf-cargo remote repository and follow the instructions. At minimum, you should end up with a registries.artifactory configuration in your .cargo/config.toml file:

   [registries.artifactory]
   index = "sparse+https://example.jfrog.io/artifactory/api/cargo/buf-cargo/index/"

   You may also need to set up credentials if your Artifactory instance is authenticated, which should be included in the instructions.

2. Install packages:

   cargo add --registry artifactory example_hello-service_community_neoeinstein-prost

NuGet

1. Click Set Up Client/CI Tool on the buf-nuget remote repository and follow the instructions. At minimum, you should end up with an Artifactory package source in your NuGet.config file:

   <packageSources>
     <add key="Artifactory" value="https://example.jfrog.io/artifactory/api/nuget/v3/buf-nuget/index.json" />
   </packageSources>

   You may also need to set up credentials if your Artifactory instance is authenticated, which should be included in Artifactory's instructions.

2. Install packages:

   dotnet add package Bsr.Example.HelloService.Grpc.Csharp