Skip to content

Use generated SDKs through JFrog Artifactory#

The Buf Schema Registry exposes generated SDKs over the standard registry APIs in each language: Go module proxy, npm registry, Maven repository, PyPI simple index, Cargo sparse registry, and NuGet v3. That means JFrog Artifactory can sit in front of the BSR the same way it sits in front of npm, PyPI, or Maven Central.

If your org already runs JFrog Artifactory as the universal binary manager for every other dependency source, putting it in front of your BSR instance keeps the BSR on the same path. Generated SDKs land in the same caching and replication layer that fronts your other remotes, JFrog Xray scans them under the same vulnerability policies that cover the rest of your stack, and Artifactory’s build-info captures them in the same provenance graph that ties artifacts to the builds that consumed them. Adding the BSR as another remote means there’s nothing new for developers, network admins, or security to manage; it’s one more entry in the Artifactory configuration they’re already maintaining.

This page walks through the Artifactory configuration for each language, then the client-side configuration to install a generated SDK through it. Examples use the connectrpc/eliza module, the same one used across the rest of the SDK docs.

Before you start#

  • You need to be a BSR instance admin and an Artifactory admin.
  • Create a bot user on your BSR instance and generate an API token. Every Artifactory remote repository below authenticates to the BSR with this bot user’s username and token, supplied as User Name and Access Token.
  • The examples below use buf.example.com as the BSR hostname and example.jfrog.io as the Artifactory hostname. Substitute your own throughout.

Go#

Add a Go remote repository in Artifactory at https://example.jfrog.io/ui/admin/repositories/remote/new:

  • Repository Key: buf-go
  • URL: https://buf.example.com/gen/go
  • User Name and Access Token: the bot-user credentials from Before you start.
  • Open the Advanced tab and check Bypass HEAD Requests.

Create a virtual Go repository named go (or edit an existing one) and add buf-go to its included items, alongside whichever upstream Go remote (go-remote) you already have.

Configure your Go client to fetch through Artifactory and to skip checksum verification for BSR modules, which the public Go sumdb doesn’t host:

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

See the GONOSUMDB documentation and the Go SDK private-modules guide for the longer explanation.

Install a generated SDK:

$ go get buf.example.com/gen/go/connectrpc/eliza/connectrpc/go

Verify the install resolved through Artifactory:

$ go list -m buf.example.com/gen/go/connectrpc/eliza/connectrpc/go

NPM#

Add an NPM remote repository in Artifactory:

  • Repository Key: buf-npm
  • URL: https://buf.example.com/gen/npm/v1
  • Repository Layout and Remote Layout Mapping: npm-default
  • User Name and Access Token: the bot-user credentials from Before you start.
  • Open the Advanced tab and check Bypass HEAD Requests.

Artifactory’s Test button often fails for this configuration even when it’s correct; see Troubleshooting.

Create a virtual NPM repository named npm and add buf-npm to its included items. To pull plugin runtime dependencies from npmjs.org through the same virtual repo, add another remote pointed at https://registry.npmjs.org/ and include it.

Configure your NPM client. The BSR exposes generated SDKs under the @buf scope on the public BSR; private instances may configure a different scope, in which case substitute it everywhere @buf appears below.

$ npm config set @buf:registry https://example.jfrog.io/artifactory/api/npm/npm/
$ npm login --registry https://example.jfrog.io/artifactory/api/npm/npm/

Install a generated SDK:

$ npm install @buf/connectrpc_eliza.connectrpc_es

Verify:

$ npm ls @buf/connectrpc_eliza.connectrpc_es

Maven and Gradle#

The Artifactory setup is shared between Maven and Gradle, since Gradle uses Maven repositories underneath. Configure the proxy once, then point either client at it.

Add a Maven remote repository in Artifactory:

  • Repository Key: buf-maven
  • URL: https://buf.example.com/gen/maven
  • In the General section, uncheck Handle Snapshots. The BSR Maven repository doesn’t publish snapshots.
  • User Name and Access Token: the bot-user credentials from Before you start.

To pull runtime dependencies from Maven Central through the same proxy, add another remote pointed at https://repo1.maven.org/maven2/ as maven-central.

Create a virtual Maven repository named maven and add buf-maven and maven-central to its included items.

Configure Maven#

Add a server entry to ~/.m2/settings.xml, replacing {ArtifactoryUsername} and {ArtifactoryToken} with your Artifactory credentials:

~/.m2/settings.xml
<settings>
  <servers>
    <server>
      <id>buf-artifactory</id>
      <username>{ArtifactoryUsername}</username>
      <password>{ArtifactoryToken}</password>
    </server>
  </servers>
</settings>

Add the repository to pom.xml, replacing {ArtifactoryMavenURL} with your virtual Maven repo’s URL:

pom.xml
<repositories>
  <repository>
    <id>buf-artifactory</id>
    <url>{ArtifactoryMavenURL}</url>
    <releases>
      <enabled>true</enabled>
    </releases>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>
</repositories>

Add the dependency. The BSR’s per-module Assets tab lists every available SDK version with its plugin combination:

pom.xml
<dependencies>
  <dependency>
    <groupId>com.example.buf.gen</groupId>
    <artifactId>connectrpc_eliza_connectrpc_kotlin</artifactId>
    <version>0.8.0.1.20230913231627.233fca715f49</version>
  </dependency>
</dependencies>

Verify:

$ mvn dependency:resolve

Configure Gradle#

Artifactory’s Set Up Client/CI Tool doesn’t generate Gradle snippets, so add the repository manually. Store credentials in a gradle.properties file using Gradle’s password credentials format:

gradle.properties
bufArtifactoryUsername={ArtifactoryUsername}
bufArtifactoryPassword={ArtifactoryToken}

Then declare the repository and dependency in your build script:

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

dependencies {
  implementation("com.example.buf.gen:connectrpc_eliza_connectrpc_kotlin:0.8.0.1.20230913231627.233fca715f49")
}
build.gradle
repositories {
  maven {
    name = 'bufArtifactory'
    url '{ArtifactoryMavenURL}'
    credentials(PasswordCredentials)
  }
}

dependencies {
  implementation 'com.example.buf.gen:connectrpc_eliza_connectrpc_kotlin:0.8.0.1.20230913231627.233fca715f49'
}

Verify:

$ ./gradlew dependencies

Python#

Add a Python remote repository in Artifactory:

  • Repository Key: buf-python
  • URL: https://buf.example.com/gen/python
  • Repository Layout: simple-default
  • Remote Layout Mapping: unset
  • Registry URL: https://buf.example.com/gen/python
  • Registry Suffix: simple
  • User Name and Access Token: the bot-user credentials from Before you start.
  • Open the Advanced tab and check Bypass HEAD Requests.

Artifactory’s Test button often fails for this configuration even when it’s correct; see Troubleshooting.

Create a virtual Python repository named python and add buf-python to its included items.

To pull plugin runtime dependencies (such as the protobuf package) from PyPI through the same proxy, add another remote repository:

  • Repository Key: pypi-official
  • URL: https://files.pythonhosted.org
  • Registry URL: https://pypi.org
  • Registry Suffix: simple

If you already have a PyPI mirror configured, use that instead.

Click Set Up Client/CI Tool on the virtual python repo and follow Artifactory’s instructions; the result writes an index-url line to ~/.pip/pip.conf:

~/.pip/pip.conf
[global]
index-url = https://<artifactory-username>:<artifactory-password-or-token>@example.jfrog.io/artifactory/api/pypi/python/simple

Install a generated SDK:

$ pip install connectrpc-eliza-protocolbuffers-python

Verify:

$ pip show connectrpc-eliza-protocolbuffers-python

Cargo#

Add a Cargo remote repository in Artifactory:

  • Repository Key: buf-cargo
  • URL: https://buf.example.com/gen/cargo
  • Repository Layout: cargo-default
  • Remote Layout Mapping: unset
  • Registry URL: https://buf.example.com/gen/cargo
  • Enable sparse index support: required. See Troubleshooting for why.
  • Allow anonymous download and search: optional. Enabling it may force a re-index, which you can trigger from Application > Artifactory > Artifacts, right-click the repo, and choose Recalculate Index.
  • User Name and Access Token: the bot-user credentials from Before you start.
  • Open the Advanced tab and check Bypass HEAD Requests.

Add the registry to ~/.cargo/config.toml:

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

If your Artifactory requires authentication, follow the credentials block in Artifactory’s Set Up Client/CI Tool instructions.

Install a generated SDK:

$ cargo add --registry artifactory connectrpc_eliza_community_neoeinstein-prost

Verify:

$ cargo tree

NuGet#

Add a NuGet remote repository in Artifactory:

  • Repository Key: buf-nuget
  • URL: https://buf.example.com/gen/nuget
  • NuGet v3 Feed URL: https://buf.example.com/gen/nuget/index.json
  • NuGet Feed Context Path: unset
  • NuGet Symbol Server URL: unset
  • Force Authentication: enabled
  • User Name and Access Token: the bot-user credentials from Before you start.

Add the package source to NuGet.config:

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

Follow the credentials block in Artifactory’s Set Up Client/CI Tool instructions for authentication.

Install a generated SDK:

$ dotnet add package BSR.Connectrpc.Eliza.Grpc.Csharp

Verify:

$ dotnet list package

Troubleshooting#

Artifactory’s Test button fails#

For NPM and Python remote repositories, Artifactory’s Test button on the remote-repo configuration page often returns an error against the BSR even when the repository is correctly configured. Fetching packages through the repo still works. There’s no setting that fixes the test result itself; ignore it and verify by running the install command for the language.

Cargo: only the sparse index is supported#

The BSR Cargo registry doesn’t expose the legacy Git-based index. Enable sparse index support must stay on for the buf-cargo remote, and clients must be on Rust 1.68 or later, where sparse registries are stable.

Go: checksum verification fails for BSR modules#

The public Go sumdb (sum.golang.org) doesn’t have entries for BSR-generated modules, so the toolchain refuses them by default. Setting GONOSUMDB to your BSR host as shown in the Go section skips sumdb verification for those modules. The Go SDK docs describe the equivalent GOPRIVATE setup for direct BSR access.