Configuring Jenkins

This guide shows you how to integrate the Artifact Cache CLI into your Jenkins pipelines.

Prerequisites

Before you begin, ensure you have:

  • Develocity Edge node (version 1.6+) deployed

  • Develocity server (version 2025.3+)

  • Develocity access key with appropriate permissions

  • Artifact Cache CLI repository credentials

  • Jenkins with Pipeline support

  • Java 21+ installed on Jenkins agents

See System Requirements for complete details.

Store Credentials in Jenkins

Navigate to Manage Jenkins > Manage Credentials and add:

ID Type Value

artifact-cache-access-key

Secret text

Your Develocity access key: <hostname>=<key_value>

artifact-cache-repo

Username with password

Credentials for gradlecom.jfrog.io

Configuration

Automatic Image Name Generation

To enable automatic image name generation, leave the ARTIFACT_CACHE_IMAGE environment variable unset.

Set the following environment variables manually:

environment {
    DEVELOCITY_ARTIFACT_CACHE_BRANCH_NAME = "${env.BRANCH_NAME}"
    DEVELOCITY_ARTIFACT_CACHE_BASE_BRANCH_NAME = "${env.CHANGE_TARGET}"
}

For multibranch pipelines, the values above automatically adapt. For regular pipelines, set them to hardcoded values:

environment {
    DEVELOCITY_ARTIFACT_CACHE_BRANCH_NAME = "main"
    DEVELOCITY_ARTIFACT_CACHE_BASE_BRANCH_NAME = "main"
}

Gradle Project Setup

Complete Pipeline Example

pipeline {
    agent any

    environment {
        // Artifact Cache Configuration
        ARTIFACT_CACHE_CLI_VERSION = '0.10.0'
        ARTIFACT_CACHE_IMAGE = 'sample-gradle'
        // Develocity
        DV_SERVER = 'https://<develocity.address>'
        // Artifact Cache CLI
        ARTIFACT_CACHE_REPO = 'https://gradlecom.jfrog.io/artifactory/develocity-artifact-cache-cli-libs-releases-local'
        // Misc
        ARTIFACT_CACHE_CLI_FILENAME = 'develocity-artifact-cache-cli'
        ARTIFACT_CACHE_OPTS = "--gradle-home=${env.HOME}/.gradle --reporting-directory=${WORKSPACE}/.develocity/artifact-cache"
    }

    stages {
        stage('Checkout repository') {
            steps {
                checkout scm
            }
        }

        stage('Provision and configure Artifact Cache') {
            steps {
                script {
                    def jdkHome = tool name: 'jdk21', type: 'jdk'
                    def artifactCacheDir = "${env.HOME}/.jenkins-tools/develocity/${env.ARTIFACT_CACHE_CLI_VERSION}"
                    def artifactCacheJar = "${artifactCacheDir}/${env.ARTIFACT_CACHE_CLI_FILENAME}.jar"

                    withCredentials([usernamePassword(credentialsId: 'artifact-cache-repo', usernameVariable: 'USER', passwordVariable: 'PASS')]) {
                        sh """
                        if [ ! -f "${artifactCacheJar}" ]; then
                            echo "Downloading Artifact Cache CLI v${env.ARTIFACT_CACHE_CLI_VERSION}..."
                            mkdir -p "${artifactCacheDir}"
                            curl --location --fail --silent --show-error \\
                              --connect-timeout 5 --max-time 30 \\
                              --retry 3 --retry-delay 3 --retry-max-time 60 \\
                              -u "\$USER:\$PASS" \\
                              "${env.ARTIFACT_CACHE_REPO}/com/gradle/${env.ARTIFACT_CACHE_CLI_FILENAME}/${env.ARTIFACT_CACHE_CLI_VERSION}/${env.ARTIFACT_CACHE_CLI_FILENAME}-${env.ARTIFACT_CACHE_CLI_VERSION}.jar" \\
                              --output "${artifactCacheJar}"
                        fi
                    """
                    }

                    // Set reusable command variables
                    env.ARTIFACT_CACHE_CMD = "${jdkHome}/bin/java -jar ${artifactCacheJar}"
                    def imageName = env.ARTIFACT_CACHE_IMAGE ? "--image-name=${env.ARTIFACT_CACHE_IMAGE}" : ""
                    env.ARTIFACT_CACHE_CMD_OPTS = "--dv-server=${env.DV_SERVER} ${imageName} ${env.ARTIFACT_CACHE_OPTS}"
                }
            }
        }

        stage('Restore from Artifact Cache') {
            steps {
                script {
                    try {
                        withCredentials([string(credentialsId: 'artifact-cache-access-key', variable: 'DEVELOCITY_ACCESS_KEY')]) {
                            sh """
                                ${env.ARTIFACT_CACHE_CMD} restore ${env.ARTIFACT_CACHE_CMD_OPTS}
                            """
                        }
                    } catch (e) {
                        echo "WARNING: Could not restore the Artifact Cache. The build will proceed but may be slower."
                    }
                }
            }
        }
        stage('Build project') {
            steps {
                sh './gradlew build'
            }
        }
    }

    post {
        success {
            script {
                try {
                    withCredentials([string(credentialsId: 'artifact-cache-access-key', variable: 'DEVELOCITY_ACCESS_KEY')]) {
                        sh """
                             ${env.ARTIFACT_CACHE_CMD} store ${env.ARTIFACT_CACHE_CMD_OPTS}
                        """
                    }
                } catch (e) {
                    echo "WARNING: Failed to store in the Artifact Cache."
                }
            }
        }
        always {
            script {
                // Persist Artifact Cache Logs
                def logPath = ".develocity/artifact-cache/artifact-cache.log"
                if (fileExists(logPath)) {
                    archiveArtifacts artifacts: logPath, allowEmptyArchive: true, fingerprint: false
                }
            }
        }
    }
}

Maven Project Setup

Configuration

Change only the ARTIFACT_CACHE_OPTS:

environment {
    ARTIFACT_CACHE_OPTS = "--maven-home=${env.HOME}/.m2"
}

Complete Pipeline Example

pipeline {
    agent any

    environment {
        // Artifact Cache Configuration
        ARTIFACT_CACHE_CLI_VERSION = '0.10.0'
        ARTIFACT_CACHE_IMAGE = 'sample-maven'
        // Develocity
        DV_SERVER = 'https://<develocity.address>'
        // Artifact Cache CLI
        ARTIFACT_CACHE_REPO = 'https://gradlecom.jfrog.io/artifactory/develocity-artifact-cache-cli-libs-releases-local'
        // Misc
        ARTIFACT_CACHE_CLI_FILENAME = 'develocity-artifact-cache-cli'
        ARTIFACT_CACHE_OPTS = "--maven-home=${env.HOME}/.m2 --reporting-directory=${WORKSPACE}/.develocity/artifact-cache"
    }

    stages {
        stage('Checkout repository') {
            steps {
                checkout scm
            }
        }

        stage('Provision and configure Artifact Cache') {
            steps {
                script {
                    def jdkHome = tool name: 'jdk21', type: 'jdk'
                    def artifactCacheDir = "${env.HOME}/.jenkins-tools/develocity/${env.ARTIFACT_CACHE_CLI_VERSION}"
                    def artifactCacheJar = "${artifactCacheDir}/${env.ARTIFACT_CACHE_CLI_FILENAME}.jar"

                    withCredentials([usernamePassword(credentialsId: 'artifact-cache-repo', usernameVariable: 'USER', passwordVariable: 'PASS')]) {
                        sh """
                        if [ ! -f "${artifactCacheJar}" ]; then
                            echo "Downloading Artifact Cache CLI v${env.ARTIFACT_CACHE_CLI_VERSION}..."
                            mkdir -p "${artifactCacheDir}"
                            curl --location --fail --silent --show-error \\
                              --connect-timeout 5 --max-time 30 \\
                              --retry 3 --retry-delay 3 --retry-max-time 60 \\
                              -u "\$USER:\$PASS" \\
                              "${env.ARTIFACT_CACHE_REPO}/com/gradle/${env.ARTIFACT_CACHE_CLI_FILENAME}/${env.ARTIFACT_CACHE_CLI_VERSION}/${env.ARTIFACT_CACHE_CLI_FILENAME}-${env.ARTIFACT_CACHE_CLI_VERSION}.jar" \\
                              --output "${artifactCacheJar}"
                        fi
                    """
                    }

                    // Set reusable command variables
                    env.ARTIFACT_CACHE_CMD = "${jdkHome}/bin/java -jar ${artifactCacheJar}"
                    def imageName = env.ARTIFACT_CACHE_IMAGE ? "--image-name=${env.ARTIFACT_CACHE_IMAGE}" : ""
                    env.ARTIFACT_CACHE_CMD_OPTS = "--dv-server=${env.DV_SERVER} ${imageName} ${env.ARTIFACT_CACHE_OPTS}"
                }
            }
        }

        stage('Restore from Artifact Cache') {
            steps {
                script {
                    try {
                        withCredentials([string(credentialsId: 'artifact-cache-access-key', variable: 'DEVELOCITY_ACCESS_KEY')]) {
                            sh """
                                ${env.ARTIFACT_CACHE_CMD} restore ${env.ARTIFACT_CACHE_CMD_OPTS}
                            """
                        }
                    } catch (e) {
                        echo "WARNING: Could not restore the Artifact Cache. The build will proceed but may be slower."
                    }
                }
            }
        }
        stage('Build project') {
            steps {
                sh './mvnw install'
            }
        }
    }

    post {
        success {
            script {
                try {
                    withCredentials([string(credentialsId: 'artifact-cache-access-key', variable: 'DEVELOCITY_ACCESS_KEY')]) {
                        sh """
                             ${env.ARTIFACT_CACHE_CMD} store ${env.ARTIFACT_CACHE_CMD_OPTS}
                        """
                    }
                } catch (e) {
                    echo "WARNING: Failed to store in the Artifact Cache."
                }
            }
        }
        always {
            script {
                // Persist Artifact Cache Logs
                def logPath = ".develocity/artifact-cache/artifact-cache.log"
                if (fileExists(logPath)) {
                    archiveArtifacts artifacts: logPath, allowEmptyArchive: true, fingerprint: false
                }
            }
        }
    }
}

Custom Maven Repository Path

If your project uses a custom Maven repository location (via -Dmaven.repo.local or settings.xml), add the --maven-repository option:

environment {
    ARTIFACT_CACHE_OPTS = "--maven-home=${env.HOME}/.m2 --maven-repository=/custom/repo"
}

npm Project Setup

Configuration

Change only the ARTIFACT_CACHE_OPTS:

environment {
    ARTIFACT_CACHE_OPTS = "--npm-home=${env.HOME}/.npm"
}

Complete Pipeline Example

pipeline {
    agent any
    environment {
        // Artifact Cache Configuration
        ARTIFACT_CACHE_CLI_VERSION = '0.10.0'
        ARTIFACT_CACHE_IMAGE = 'sample-npm'
        // Develocity
        DV_SERVER = 'https://<develocity.address>'
        // Artifact Cache CLI
        ARTIFACT_CACHE_REPO = 'https://gradlecom.jfrog.io/artifactory/develocity-artifact-cache-cli-libs-releases-local'
        // Misc
        ARTIFACT_CACHE_CLI_FILENAME = 'develocity-artifact-cache-cli'
        ARTIFACT_CACHE_OPTS = "--npm-home=${env.HOME}/.npm --reporting-directory=${WORKSPACE}/.develocity/artifact-cache"
    }
    stages {
        stage('Checkout repository') {
            steps {
                checkout scm
            }
        }
        stage('Provision and configure Artifact Cache') {
            steps {
                script {
                    def jdkHome = tool name: 'jdk21', type: 'jdk'
                    def artifactCacheDir = "${env.HOME}/.jenkins-tools/develocity/${env.ARTIFACT_CACHE_CLI_VERSION}"
                    def artifactCacheJar = "${artifactCacheDir}/${env.ARTIFACT_CACHE_CLI_FILENAME}.jar"
                    withCredentials([usernamePassword(credentialsId: 'artifact-cache-repo', usernameVariable: 'USER', passwordVariable: 'PASS')]) {
                        sh """
                        if [ ! -f "${artifactCacheJar}" ]; then
                            echo "Downloading Artifact Cache CLI v${env.ARTIFACT_CACHE_CLI_VERSION}..."
                            mkdir -p "${artifactCacheDir}"
                            curl --location --fail --silent --show-error \\
                              --connect-timeout 5 --max-time 30 \\
                              --retry 3 --retry-delay 3 --retry-max-time 60 \\
                              -u "\$USER:\$PASS" \\
                              "${env.ARTIFACT_CACHE_REPO}/com/gradle/${env.ARTIFACT_CACHE_CLI_FILENAME}/${env.ARTIFACT_CACHE_CLI_VERSION}/${env.ARTIFACT_CACHE_CLI_FILENAME}-${env.ARTIFACT_CACHE_CLI_VERSION}.jar" \\
                              --output "${artifactCacheJar}"
                        fi
                    """
                    }
                    // Set reusable command variables
                    env.ARTIFACT_CACHE_CMD = "${jdkHome}/bin/java -jar ${artifactCacheJar}"
                    def imageName = env.ARTIFACT_CACHE_IMAGE ? "--image-name=${env.ARTIFACT_CACHE_IMAGE}" : ""
                    env.ARTIFACT_CACHE_CMD_OPTS = "--dv-server=${env.DV_SERVER} ${imageName} ${env.ARTIFACT_CACHE_OPTS}"
                }
            }
        }
        stage('Restore from Artifact Cache') {
            steps {
                script {
                    try {
                        withCredentials([string(credentialsId: 'artifact-cache-access-key', variable: 'DEVELOCITY_ACCESS_KEY')]) {
                            sh """
                                ${env.ARTIFACT_CACHE_CMD} restore ${env.ARTIFACT_CACHE_CMD_OPTS}
                            """
                        }
                    } catch (e) {
                        echo "WARNING: Could not restore the Artifact Cache. The build will proceed but may be slower."
                    }
                }
            }
        }
        stage('Build project') {
            steps {
                sh 'npm ci && npm run build'
            }
        }
    }
    post {
        success {
            script {
                try {
                    withCredentials([string(credentialsId: 'artifact-cache-access-key', variable: 'DEVELOCITY_ACCESS_KEY')]) {
                        sh """
                             ${env.ARTIFACT_CACHE_CMD} store ${env.ARTIFACT_CACHE_CMD_OPTS}
                        """
                    }
                } catch (e) {
                    echo "WARNING: Failed to store in the Artifact Cache."
                }
            }
        }
        always {
            script {
                // Persist Artifact Cache Logs
                def logPath = ".develocity/artifact-cache/artifact-cache.log"
                if (fileExists(logPath)) {
                    archiveArtifacts artifacts: logPath, allowEmptyArchive: true, fingerprint: false
                }
            }
        }
    }
}