Develocity Artifact Cache and Setup Cache User Manual

How Artifact Cache CLI Works

Artifact Cache CLI stores and restores build artifacts to the Develocity Artifact Cache and Setup Cache service on Develocity Edge nodes through three sequential phases: Restore, Build, and Store. Edge nodes manage the available cache storage through an eviction policy, and Develocity manages access control for Artifact Cache CLI clients.

Artifact Cache and Setup Cache Overview

Obtaining the Artifact Cache CLI Binary

A CI job needs the develocity-artifact-cache-cli JAR file on the agent before it can restore or store cache content. There are two ways to put it there: fetch it from a Develocity Edge node, or host a copy inside your own network.

Downloading From an Edge Node

Develocity Edge nodes serve the develocity-artifact-cache-cli JAR file, so a CI job fetches the CLI from the Edge it already uses for the cache. You host nothing, and the version a CI agent receives is the version the job requested.

Requesting a version that an Edge does not yet hold makes Develocity download it from the public release channel, verify its checksum, and pass it to the Edge, which retains it for later requests. An operator can also seed a version, which serves it without any access to the public release channel.

This method requires Edge node 2.3.0 or later, connected to Develocity 2026.3.0 or later.

Download Command

Request an exact version from your Edge, authenticating with the same Develocity access key your builds use for the cache:

curl --fail --location \
  --connect-timeout 5 --max-time 120 \
  --retry 3 --retry-delay 3 --retry-max-time 180 \
  --header "Authorization: Bearer ACCESS_KEY" \
  --output develocity-artifact-cache-cli.jar \
  https://edge.example.internal/edge/assets/artifact-cache-cli/1.5.0

The retry and timeout options keep a transient network fault from failing the job. The body timeout is longer than you would set against your own artifact repository, because the first request for a version an Edge does not hold waits for Develocity to fetch and verify it.

The access key’s user needs permission to read Build Cache data, which CI agent users configured for Artifact Cache already have.

Add this step to your CI job before the restore command, and run the resulting JAR file as you would a copy you host yourself.

Verification

Develocity verifies the JAR file’s SHA-256 checksum against the published checksum before an Edge stores it. The Edge does not serve the checksum or the PGP signature files alongside the JAR file, so a CI job cannot repeat that verification locally. To verify a release yourself, download it from the release channel as described in Hosting the Binary Yourself.

For the endpoint reference, the storage and eviction behavior, and the seeding procedure, see Serving the Artifact Cache CLI in the Develocity Edge User Manual.

Hosting the Binary Yourself

Download the CLI binary, upload it to your internal artifact repository (such as Artifactory, Nexus, or a file server), and point your CI jobs at that copy. Host the binary yourself when your security process requires reviewing every binary before it runs on a build machine, or when your Edge nodes predate 2.3.0.

Keeping the binary inside your network gives you:

Control over artifact availability
Compliance with corporate security policies
Download speeds within your own network

Download

You can download the latest version of develocity-artifact-cache-cli JAR file and its associated files from the following links:

curl -L -o develocity-artifact-cache-cli.jar https://docs.develocity.ai/downloads/develocity-artifact-cache-cli/develocity-artifact-cache-cli-1.5.0.jar

To validate the binary:

Download the checksum file:

curl -L -o develocity-artifact-cache-cli-1.5.0.jar.sha256 https://docs.develocity.ai/downloads/develocity-artifact-cache-cli/develocity-artifact-cache-cli-1.5.0.jar.sha256

Validate the binary against the checksum file:

echo "$(cat develocity-artifact-cache-cli-1.5.0.jar.sha256)  develocity-artifact-cache-cli.jar" | sha256sum --check

If valid, the output is:
Output
```
develocity-artifact-cache-cli: OK
```
If the check fails, sha256 exits with nonzero status and prints output similar to:
Output
```
develocity-artifact-cache-cli: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match
```
Download the same version of the binary and checksum.

Verifying the GPG Signature

The develocity-artifact-cache-cli JAR is published alongside its PGP signature. The public key is published to https://keyserver.ubuntu.com. You can verify the signature as follows:

curl -OL https://docs.develocity.ai/downloads/develocity-artifact-cache-cli/develocity-artifact-cache-cli-1.5.0.jar && \
  curl -OL https://docs.develocity.ai/downloads/develocity-artifact-cache-cli/develocity-artifact-cache-cli-1.5.0.jar.asc && \
  gpg --keyserver keyserver.ubuntu.com --recv-key 7B79ADD11F8A779FE90FD3D0893A028475557671 && \
  gpg --verify develocity-artifact-cache-cli-1.5.0.jar.asc develocity-artifact-cache-cli-1.5.0.jar

The output of the last command should look similar to the following:

Output

gpg: Signature made Tue Jul 28 08:44:40 2026 UTC
gpg:                using RSA key 893A028475557671
gpg: Good signature from "Gradle Inc. <[email protected]>" [unknown]
gpg: WARNING: This key has been revoked by its owner!
gpg:          This could mean that the signature is forged.
gpg: reason for revocation: Key is superseded
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7B79 ADD1 1F8A 779F E90F  D3D0 893A 0284 7555 7671

This verifies that the artifact was signed with the private key that corresponds to the imported public key. The warning is emitted because you haven’t explicitly trusted the imported key (therefore [unknown]). One way of establishing trust is to verify the fingerprint over a secure channel. Please contact technical support should you want to do so.

This key was superseded by a new Develocity signing key, so gpg reports it as revoked. The signature is still valid: the revocation reason is Key is superseded, which leaves signatures made with the key intact. Fetch the key from keyserver.ubuntu.com as shown above. keys.openpgp.org no longer serves the user IDs of this key, and gpg refuses to import a key that carries none.

Requirements

For system requirements to use Develocity Artifact Cache and Setup Cache, see System Requirements.

Getting Started

See Configuring GitHub Actions and Configuring Jenkins to get started on a specific CI platform.

Artifact Cache CLI Commands

Refer to the Artifact Cache CLI Commands Reference for detailed information on available commands and their usage.

Develocity Artifact Cache and Setup Cache Operation Flow

Artifact Cache CLI connects to a Develocity Edge node and runs three sequential phases for each CI job.

Edge Discovery

The Artifact Cache CLI uses Edge discovery to connect to the optimal Edge:

Artifact Cache CLI reads the access key of a CI agent Develocity user from the environment variable DEVELOCITY_ACCESS_KEY.
Access key identifies a Develocity user.
The CI agent Develocity user has the Edge location configured.
Artifact Cache CLI connects exclusively to that Edge for the Restore and Store phases.

Alternatively, connect directly to a specific Edge node as described in Connecting Without Edge Discovery.

Connecting Without Edge Discovery

The --dv-edge option connects the Artifact Cache CLI to one Edge node, bypassing discovery through the Develocity server. A direct connection has two parts:

Pass --dv-edge=<edge_url> instead of --dv-server=<server_url>.
Include an entry for the Edge host in DEVELOCITY_ACCESS_KEY.

A discovery-based setup does not need the second part. The Artifact Cache CLI authenticates against the Edge it connects to, so a value that covers only the Develocity server host leaves the request unauthenticated and the Edge rejects it.

Restoring From a Specific Edge

export DEVELOCITY_ACCESS_KEY=edge.example.com=abcd1234efgh5678

java -jar develocity-artifact-cache-cli.jar restore \
  --dv-edge=https://edge.example.com \
  --gradle-home=$HOME/.gradle

One access key value can carry entries for several hosts, separated by semicolons. The Artifact Cache CLI uses the entry matching the host it connects to and ignores the others, so a single CI secret can serve both discovery-based and direct connections.

Access Key Covering the Develocity Server and an Edge

export DEVELOCITY_ACCESS_KEY=develocity.example.com=abcd1234efgh5678;edge.example.com=ijkl9012mnop3456

See Environment Variables for the full access key format.

Restore Phase

CI job starts: A fresh ephemeral CI agent is created.
Checkout code: The repository is cloned.
Artifact Cache CLI queries Edge: Requests the image for this job/branch.
Edge returns image: Lists all known artifacts for this job.
Restore artifacts: Artifact Cache CLI downloads artifacts.

If an existing caching solution is leveraged by the ephemeral CI agent, be aware that it might clash with Artifact Cache and/or Setup Cache, potentially causing suboptimal caching performance or undefined behavior.

The checkout step must be performed before the restore command.

Build Phase

Build runs: The build tool uses the restored artifacts.

Store Phase

Build completes: The build tool process exits.
Artifact Cache CLI scans directories: Identifies new or changed artifacts.
Store new artifacts: Uploads to the Edge node.
Update image: Records the up-to-date artifact list.
Image stored to Edge: The updated image is ready for use by the next CI job.

Observability

Build Scan Reporting

The Common Custom User Data Gradle plugin (version 2.1.0 or above) and Common Custom User Data Maven extension automatically add Artifact Cache and Setup Cache configuration and restore phase metrics to every Build Scan as Custom Values.

Example Build Scan with Artifact Cache and Setup Cache Reporting

The "Artifact Cache: Restore wall-clock duration" value is the total duration of the restore phase from both the Artifact Cache and Setup Cache.

Develocity Reporting and Visualization

The "Dependency Caching" dashboard in Develocity Reporting and Visualization provides an overview of the ratio of dependencies downloaded compared to resolved from the local cache, across all projects and builds. The dashboard supports Gradle and Maven builds running locally and on CI, and detects cached dependency files regardless of the caching solution used. When Artifact Cache is enabled, the visualizations display the actual reduction in dependency downloads achieved by the feature. The dashboard includes filters by build tool, project, and tags to enable in-depth analysis of caching performance.

Dependency Caching Dashboard

The "Dependency Caching" dashboard requires Develocity 2026.1 and Develocity Gradle plugin 4.4.0 or Develocity Maven extension 2.4.0.

The "Repository Stability" dashboard in Develocity Reporting and Visualization provides an overview of the stability of the remote binary repositories that builds depend on. A repository is unstable when the build process encounters inconsistent or unpredictable download outcomes when resolving dependencies from a repository. Repository instability slows builds even when they ultimately succeed, and in the worst case causes them to fail. With Artifact Cache enabled, the volume of requests to downstream repositories is reduced, improving overall repository and build stability. The dashboard includes filters by build tool, project, and tags to enable in-depth analysis of caching performance.

Repository Stability Dashboard

The "Repository Stability" dashboard requires Develocity 2026.2.0.

Develocity Artifact Cache and Setup Cache Service Monitoring

The Develocity Artifact Cache and Setup Cache service exposed by Edge nodes can be monitored by following the Monitoring section of the Develocity Edge User Manual.