---
component: artifact-cache
version: "1.5"
slug: artifact-cache/configure-jenkins
canonical_url: "https://docs.develocity.ai/artifact-cache/1.5/how-to/configure-jenkins/"
title: "Configuring Jenkins"
description: "Configure the Develocity Artifact Cache CLI in Jenkins pipelines to cache Maven, Gradle, npm, pip, and SonarScanner dependencies and Setup Cache artifacts."
keywords:
  - "Jenkins plugin"
  - "Artifact Cache"
status: current
---

<!-- llms-index: https://docs.develocity.ai/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.develocity.ai/artifact-cache/1.5/user-manual/#hosting-cli-binary)
    
*   Jenkins with Pipeline support
    
*   Java 21+ installed on Jenkins agents
    

See [System Requirements](https://docs.develocity.ai/artifact-cache/1.5/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="automatic-image-name-generation"></a>

### Automatic Image Name Generation

By default, Artifact Cache CLI generates an image name automatically when you leave the `ARTIFACT_CACHE_IMAGE` environment variable unset. Automatic generation is the recommended approach: it derives the name from the build context, your project’s repository data, and the CI runner’s environment, so you don’t have to choose or maintain a name yourself.

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="overriding-the-generated-name"></a>

#### Overriding the Generated Name

Set an explicit name only when you need to control the value, for example to share one cache across differently-named jobs. Provide it with the `--image-name` CLI option or the `ARTIFACT_CACHE_IMAGE` environment variable.

<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.develocity.ai/gradle/4.5/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.5.0'
        // ARTIFACT_CACHE_IMAGE is intentionally omitted so the image name is
        // generated automatically, which is the recommended default. Set it only
        // when you need to override the generated name.
        // 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=${ env.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-2"></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.5.0'
        // ARTIFACT_CACHE_IMAGE is intentionally omitted so the image name is
        // generated automatically, which is the recommended default. Set it only
        // when you need to override the generated name.
        // 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=${ env.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-3"></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.5.0'
        // ARTIFACT_CACHE_IMAGE is intentionally omitted so the image name is
        // generated automatically, which is the recommended default. Set it only
        // when you need to override the generated name.
        // 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=${ env.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="sonar-setup"></a>

## SonarScanner Caching

SonarScanner caching layers on top of your existing project setup. The Artifact Cache CLI auto-detects the SonarScanner user home from `$SONAR_USER_HOME`, falling back to `~/.sonar`. No extra configuration is required as long as the directory exists when `restore` or `store` runs.

> [!TIP]
> Expect image growth of roughly 50 to 100 MB per analyzer version stored.

If the directory is created during build execution, pin it explicitly by appending `--sonar-home` to `ARTIFACT_CACHE_OPTS`:

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

To opt out of SonarScanner caching even when the user home is present, exclude it from auto-detection:

```groovy
environment {
    ARTIFACT_CACHE_OPTS = "--gradle-home=${ env.HOME }/.gradle --no-autodetect=SONAR"
}
```

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

## Related Documentation

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