Artifactory

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.

Go setup

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

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

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

Individual developers

1. Click Set me up 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 GOPRIVATE documentation for more.

   $ export GOPRIVATE=buf.example.com/gen/go
   

4. Install modules:

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

NPM setup

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

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

3. 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 under npm

4. 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/

Individual developers

1. Click Set me up 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 setup

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

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

3. 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/

4. Create a new virtual repository named maven, or use an existing virtual Maven repository.

   • Edit the virtual repository and add buf-maven and maven-central to the included items under maven

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')
}