The Buf Schema Registry (BSR) provides remote packages 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 article 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.
Go setup
-
First, add a new Go remote repository to your Artifactory instance at
https://example.jfrog.io/ui/admin/repositories/remote/new
.- Set Key to
buf-go
- Set URL to
https://buf.example.com/gen/go
- Open the Advanced tab and check Bypass HEAD Requests
- Set Key to
-
In your BSR, create a server machine user with a token. Then set the User Name and Access Token of the
buf-go
repository in Artifactory to the BSR user name and token of the server machine user that you created. -
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 undergo
- Ensure that the
go-remote
remote repository is also added to included items
- Edit the virtual repository and add
Individual developers
-
Click Set me up on the
go
virtual repository and follow the instructions. -
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"
-
Stop the go client from trying to resolve the sum with the global sumdb, see the GOPRIVATE documentation for more.
$ export GOPRIVATE=buf.example.com/gen/go
-
Install modules:
$ go get buf.example.com/gen/go/acme/petapis/protocolbuffers/go
NPM setup
-
First, add a new NPM remote repository to your Artifactory instance at
https://example.jfrog.io/ui/admin/repositories/remote/new
.- Set Key to
buf-npm
- Set URL to
https://buf.example.com/gen/npm/v1
- Set Repository Layout and Remote Layout Mapping to npm-default
- Open the Advanced tab and check Bypass HEAD Requests
- Set Key to
-
In your BSR, create a server machine user with a token. Then set the User Name and Access Token of the
buf-npm
repository in Artifactory to the BSR user name and token of the server machine user that you created. -
Create a new virtual repository named
npm
, or use an existing virtual NPM repository.- Edit the virtual repository and add
buf-npm
to the included items undernpm
- Edit the virtual repository and add
-
Add another remote repository to act as a mirror for the official npm registry:
- Set Key to
npm-official
- Set URL to
https://registry.npmjs.org/
- Set Key to
Individual developers
-
Click Set me up on the
npm
virtual repository and follow the instructions. -
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/
-
Authenticate with Artifactory:
$ npm login
-
Install packages:
$ npm install @bufteam/example_hello-service.protocolbuffers_js
Maven setup
-
First, add a new Maven remote repository to your Artifactory instance at
https://example.jfrog.io/ui/admin/repositories/remote/new
.- Set Key to
buf-maven
- Set URL to
https://buf.example.com/gen/maven
- Scroll down to the General section and uncheck Handle Snapshots - the Buf Maven Repository does not support snapshots
- Set Key to
-
In your BSR, create a server machine user with a token. Then set the User Name and Access Token of the
buf-maven
repository in Artifactory to the BSR user name and token of the server machine user that you created. -
Add another remote repository to act as a mirror for Maven Central:
- Set Key to
maven-central
- Set URL to
https://repo1.maven.org/maven2/
- Set Key to
-
Create a new virtual repository named
maven
, or use an existing virtual Maven repository.- Edit the virtual repository and add
buf-maven
andmaven-central
to the included items undermaven
- Edit the virtual repository and add
Individual developers
Click Set me up on the maven
virtual repository and follow the instructions.
mvn
For mvn
, you 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.
<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:
<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 will have a listing of versions for your module with all of the plugins on your
instance. For example:
<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 does not 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:
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:
repositories {
maven {
name = "bufArtifactory"
url = uri("{ArtifactoryMavenURL}")
credentials(PasswordCredentials::class)
}
}
repositories {
maven {
name = 'bufArtifactory'
url "{ArtifactoryMavenURL}"
credentials(PasswordCredentials)
}
}
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 will have a listing of versions for your module with
all of the plugins on your instance. For example:
dependencies {
implementation("com.example.buf.gen:connectrpc_eliza_bufbuild_connect-kotlin:0.1.8.3.20230727062025.d8fbf2620c60")
}
dependencies {
implementation('com.example.buf.gen:connectrpc_eliza_bufbuild_connect-kotlin:0.1.8.3.20230727062025.d8fbf2620c60')
}