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

<a id="component-eol-banner"></a>

You are viewing **Develocity Artifact Cache CLI 0.10**. To view the latest available version of the docs, see [1.1](https://docs.gradle.com/develocity/artifact-cache/1.1/how-to/configure-jenkins/).

# 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 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](https://docs.gradle.com/develocity/artifact-cache/0.10/reference/requirements/) for complete details.

<a id="hosting-the-artifact-cache-cli-binary"></a>

## Hosting the Artifact Cache CLI Binary

> [!IMPORTANT]
> 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](https://support.gradle.com/contact) the Develocity support team to obtain the Artifact Cache CLI binary.

<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="complete-pipeline-example"></a>

### Complete Pipeline Example

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

<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 = '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
                }
            }
        }
    }
}
```

<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 = '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
                }
            }
        }
    }
}
```

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

## Related Documentation

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