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

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

Hosting the Artifact Cache CLI Binary

 You must host the Artifact Cache CLI binary within your internal network. This is required for security and reliability.

Download the CLI binary and upload it to your internal artifact repository (such as Artifactory, Nexus, or a simple file server). This approach ensures:

  • Control over artifact availability

  • Compliance with corporate security policies

  • Optimal download speeds

Please contact the Develocity support team to obtain the Artifact Cache CLI binary.

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

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://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 = '0.10.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 = '0.10.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
                }
            }
        }
    }
}