---
component: artifact-cache
version: "1.1"
slug: artifact-cache/configure-jenkins
canonical_url: "https://docs.gradle.com/develocity/artifact-cache/1.1/how-to/configure-jenkins/"
title: "Configuring Jenkins"
description: "How to configure Artifact Cache CLI in Jenkins pipelines"
keywords: []
status: current
---

<!-- llms-index: https://docs.gradle.com/develocity/llms.txt -->

# Configuring Jenkins

<a id="preamble"></a>

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

<a id="prerequisites"></a>

## 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](https://docs.gradle.com/develocity/artifact-cache/1.1/#hosting-cli-binary)
    
*   Jenkins with Pipeline support
    
*   Java 21+ installed on Jenkins agents
    

See [System Requirements](https://docs.gradle.com/develocity/artifact-cache/1.1/reference/requirements/) for complete details.

<a id="configuration"></a>

## Configuration

<a id="storing-credentials"></a>

### Storing Credentials

Navigate to **Manage Jenkins > Manage Credentials** and add:

  
| ID | Type | Value |
| --- | --- | --- |
| artifact-cache-access-key | Secret text | Your Develocity access key: \= |
| artifact-cache-repo | Username with password | Credentials for your internal artifact repository |

> [!NOTE]
> 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.

<a id="configuration-2"></a>

## Configuration

<a id="automatic-image-name-generation"></a>

### 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](https://www.jenkins.io/doc/book/pipeline/multibranch/), set these values dynamically:

```groovy
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:

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

<a id="gradle-setup"></a>

## Gradle Project Setup

<a id="shared-build-logic-caching"></a>

### 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](https://docs.gradle.com/develocity/gradle/4.4/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.
    

<a id="complete-pipeline-example"></a>

### Complete Pipeline Example

```groovy
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
                }
            }
        }
    }
}
```

<a id="maven-setup"></a>

## Maven Project Setup

<a id="configuration-3"></a>

### Configuration

Change only the `ARTIFACT_CACHE_OPTS`:

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

<a id="complete-pipeline-example-2"></a>

### Complete Pipeline Example

```groovy
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
                }
            }
        }
    }
}
```

<a id="custom-maven-repository-path"></a>

### 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:

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

<a id="npm-setup"></a>

## npm Project Setup

<a id="configuration-4"></a>

### Configuration

Change only the `ARTIFACT_CACHE_OPTS`:

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

<a id="complete-pipeline-example-3"></a>

### Complete Pipeline Example

```groovy
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
                }
            }
        }
    }
}
```

<a id="related-documentation"></a>

## Related Documentation

*   [CLI Commands Reference](https://docs.gradle.com/develocity/artifact-cache/1.1/reference/cli-commands/)