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 2.0.0+) deployed

  • Develocity server (version 2026.1.0+)

  • Develocity access key with appropriate permissions

  • Access to the Artifact Cache CLI binary hosted in your internal network

  • Jenkins with Pipeline support

  • Java 21+ installed on Jenkins agents

See System Requirements for complete details.

Configuration

Storing Credentials

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 your internal artifact repository
If you use a custom internal artifact repository location, verify the "Provision and configure Artifact Cache" stage in your pipeline. Ensure the curl command’s authentication parameters (-u) and download URL match your repository’s requirements.

Configuration

Automatic Image Name Generation

To enable automatic image name generation, leave the ARTIFACT_CACHE_IMAGE environment variable unset. This generation process is based on the build context, project’s repository data, and the CI Runner’s environment.

The Artifact Cache CLI inspects the following environment variables when generating image names for Jenkins:

  • JOB_NAME

  • JENKINS_HOME

For Jenkins, you must also manually set the following environment variables:

  • DEVELOCITY_ARTIFACT_CACHE_BRANCH_NAME - The current repository branch (e.g., main or feature-branch-name)

  • DEVELOCITY_ARTIFACT_CACHE_BASE_BRANCH_NAME - The base repository branch (e.g., main)

For multibranch pipelines, set these values dynamically:

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

The values above automatically adapt for multi-branch pipelines. For regular pipelines, set them to hard-coded values:

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

Gradle Project Setup

Shared Build Logic Caching

Starting with Artifact Cache CLI version 1.1.0, the Setup Cache automatically caches shared Gradle build logic defined in buildSrc and included builds. This feature requires the Develocity Gradle Plugin version 4.4.1 or later, and has the following constraints:

  • The absolute project checkout path must remain constant across builds. Jenkins uses a stable workspace path by default (/var/lib/jenkins/workspace/<job-name>), but renaming jobs or using custom workspace directories invalidates the cache.

  • The repository checkout must happen before the restore command.

Complete Pipeline Example

pipeline {
    agent any

    environment {
        // Artifact Cache Configuration
        ARTIFACT_CACHE_CLI_VERSION = '1.1.0'
        ARTIFACT_CACHE_IMAGE = 'sample-gradle'
        // Develocity
        DV_SERVER = 'https://<develocity.address>'
        // Artifact Cache CLI
        ARTIFACT_CACHE_REPO = 'https://your-internal-repo.example.com/path/to/artifact-cache-cli'
        // 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 = '1.1.0'
        ARTIFACT_CACHE_IMAGE = 'sample-maven'
        // Develocity
        DV_SERVER = 'https://<develocity.address>'
        // Artifact Cache CLI
        ARTIFACT_CACHE_REPO = 'https://your-internal-repo.example.com/path/to/artifact-cache-cli'
        // 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 = '1.1.0'
        ARTIFACT_CACHE_IMAGE = 'sample-npm'
        // Develocity
        DV_SERVER = 'https://<develocity.address>'
        // Artifact Cache CLI
        ARTIFACT_CACHE_REPO = 'https://your-internal-repo.example.com/path/to/artifact-cache-cli'
        // 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
                }
            }
        }
    }
}