---
component: artifact-cache
version: "1.7"
slug: artifact-cache/configure-github-actions
canonical_url: "https://docs.develocity.ai/artifact-cache/1.7/how-to/configure-github-actions/"
title: "Configuring GitHub Actions"
description: "Configure the Develocity Artifact Cache CLI in GitHub Actions to cache Maven, Gradle, npm, pip, and SonarScanner dependencies and Setup Cache artifacts."
keywords:
- "GitHub Actions"
- "Artifact Cache"
status: current
---
# Configuring GitHub Actions
This guide shows you how to integrate the Artifact Cache CLI into your GitHub Actions workflows.
There are two supported ways to do this:
* The **Develocity Artifact Cache GitHub Action** ([repository](https://github.com/gradle/develocity-artifact-cache-github-action)) is the officially supported and recommended path. It wraps the Artifact Cache CLI, restores the cache before your build, and stores it afterward, with a single step.
* The **manual CLI setup** downloads and drives the CLI yourself. Use it on air-gapped or restricted-network runners, when your organization does not permit third-party GitHub Actions, or when you need control beyond the Action’s inputs.
## Prerequisites
Before you begin, ensure you have:
* Develocity Edge node (version 2.3.0+) deployed
* Develocity server (version 2026.3.0+)
* Develocity access key with appropriate permissions
* Access to the Artifact Cache CLI binary, [served by an Edge node or hosted in your internal network](https://docs.develocity.ai/artifact-cache/1.7/download-the-cli/)
See [System Requirements](https://docs.develocity.ai/artifact-cache/1.7/reference/requirements/) for complete details.
## Disabling Conflicting Cache Actions
The Artifact Cache provides complete caching functionality. Disable caching in these GitHub Actions to prevent conflicts:
**setup-gradle (gradle/actions/setup-gradle)** — Apply it **before** the Artifact Cache Action and [disable its Gradle User Home caching](https://github.com/gradle/actions/blob/main/docs/setup-gradle.md#disabling-caching). With `gradle/actions` 6.4.0 or newer, set `cache-provider: external`, which keeps the job summary accurate by reporting that caching is handled externally rather than turned off; on older versions, set `cache-disabled: true`. Ordering matters: `setup-gradle` establishes the Gradle User Home and exports `GRADLE_USER_HOME`, which the Artifact Cache CLI auto-detects, so running it first ensures the cache is restored into and stored from the Gradle User Home your build uses. If you do not use `setup-gradle`, the CLI falls back to the default Gradle User Home (`~/.gradle`) that `./gradlew` uses, so the basic template needs no extra configuration; this coordination matters only when a custom `GRADLE_USER_HOME` is set.
**Setup Java (actions/setup-java)** — [Don’t enable caching](https://github.com/actions/setup-java#caching-packages-dependencies) - omit the `cache` parameter.
**Cache Action (actions/cache)** — Don’t use for Gradle or Maven dependencies. See [examples](https://github.com/actions/cache/blob/main/examples.md#java---gradle) for what to avoid.
## Using the GitHub Action
The `gradle/develocity-artifact-cache-github-action` Action is the officially supported way to run the Artifact Cache CLI in GitHub Actions. It restores the cache in its main step, runs your build, and stores the cache in a post step after a successful build, so you do not write the restore and store steps yourself. By default it downloads the CLI from the public Develocity host, so you do not need to host the binary to get started.
When `develocity-url` addresses a Develocity Edge node running version 2.3.0 or later, the Action downloads the CLI from that Edge node instead, using the short-lived token it already exchanged for the cache restore as the bearer credential. An explicit `cli-repository` value always wins over the Edge node, so set it to skip this detection and download from your own mirror instead.
The Action targets one Develocity endpoint: set `develocity-url` to reach a Develocity server (passed to the CLI as `--dv-server`), or `develocity-edge-url` to target a Develocity Edge directly (`--dv-edge`). Provide exactly one (they are mutually exclusive), and whichever you set also identifies the host for the access key and short-lived-token exchange.
Cache activity is best-effort: a restore or store problem is surfaced as a warning, never a build failure. After the run, the Action adds a single cache-activity table to the GitHub job summary, with a row for the restore and, when it runs, the store. Gradle and Maven builds also surface cache metrics in their Build Scan.
GitHub Actions Job Summary for the Artifact Cache Action
The Action runs the Artifact Cache CLI under Java 21 (a minimum floor). On GitHub-hosted runners it resolves a suitable JDK automatically from the pre-set `JAVA_HOME_*` variables, so no `setup-java` step is required for the Action itself. It is supported on GitHub-hosted Linux, macOS, and Windows runners, and on self-hosted Linux runners. The examples below add `actions/setup-java` to provide the JDK your build runs on.
### Storing the Access Key
In your GitHub repository settings, navigate to **Settings > Secrets and variables > Actions** and add a `DEVELOCITY_ACCESS_KEY` secret.
The `develocity-access-key` input takes the key in `=` form, matching the `DEVELOCITY_ACCESS_KEY` format used by the DV build agents and `setup-gradle`; a bare key value is not accepted. The Action uses the entry for the chosen endpoint host (whichever of `develocity-url` or `develocity-edge-url` is set). It is the only key source: the Action does not read the `DEVELOCITY_ACCESS_KEY` environment variable or local key files.
The Action exchanges this long-lived key for a short-lived Develocity token, handing it to the Artifact Cache CLI through a private, subprocess-scoped environment variable. It uses that token for its own cache restore and store and, when it downloads the CLI from a Develocity Edge node, as the bearer credential for that download. It does not set `DEVELOCITY_ACCESS_KEY` for other steps, so neither the long-lived key nor the token is propagated to the rest of the workflow. Steps that need to authenticate with Develocity (for example, to publish a Build Scan) should obtain their own token; `gradle/actions/setup-gradle` performs the same exchange and exports it for Gradle builds. The token lasts two hours by default; raise `develocity-token-expiry` only if a build could run long enough for the token to expire before the post-step store.
The resolved key is masked in the workflow log. Prefer an access key scoped to only the servers and permissions it needs.
### Authenticating With an OIDC Token
Requires Develocity 2026.3 or later, with a workload identity rule configured for your CI provider. See [Workload Identity](https://docs.develocity.ai/2026.3/administration/access-control/workload-identity/).
As an alternative to a long-lived `DEVELOCITY_ACCESS_KEY` secret, a workflow can mint a short-lived OIDC token from GitHub’s OIDC provider (see the [GitHub Actions OpenID Connect documentation](https://docs.github.com/en/actions/concepts/security/openid-connect)) and pass it to `develocity-access-key` in place of the access key value. Develocity validates the token against the issuer, audience, and claim requirements configured on the matching workload identity rule. When you use an OIDC token, you no longer need to store an access key as a GitHub Actions secret.
Grant the job `id-token: write` permission, mint the token with `actions/github-script`, mask it, and expose it as a step output in host-qualified `«server host name»=«token»` form:
```yaml
name: Artifact Cache with OIDC
on: push
permissions:
id-token: write
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v7
- name: Get GitHub OIDC Workload Identity token
id: dv-token
uses: actions/github-script@v7
with:
script: |
const token = await core.getIDToken('https://develocity.example.com')
core.setSecret(token)
core.setOutput('key', `develocity.example.com=${token}`)
- name: Develocity Artifact Cache
uses: gradle/develocity-artifact-cache-github-action@v1
with:
develocity-url: https://develocity.example.com
develocity-access-key: ${{ steps.dv-token.outputs.key }}
```
To mint the token without `actions/github-script`, replace the mint step with a `curl` request to GitHub’s OIDC endpoint, using the `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN` variables that `id-token: write` exposes:
```yaml
- name: Get GitHub OIDC Workload Identity token
id: dv-token
run: |
token=$(curl -sH "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://develocity.example.com" | jq -r .value)
echo "::add-mask::$token"
echo "key=develocity.example.com=$token" >> "$GITHUB_OUTPUT"
```
This step produces the same `steps.dv-token.outputs.key` value, so the Artifact Cache step is unchanged.
The audience passed to `getIDToken` (or to `curl`) must match the audience configured on the workload identity rule, and the hostname prefix on `develocity-access-key` must match the host in `develocity-url` (or `develocity-edge-url`). The token is short-lived, so mint it in every job that needs cache access rather than sharing it across jobs.
### Gradle
This workflow caches Gradle dependencies through the Action.
```yaml
name: Artifact Cache Gradle template
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v7
- name: Set up Java
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- name: Develocity Artifact Cache
uses: gradle/develocity-artifact-cache-github-action@v1
with:
develocity-url: https://develocity.example.com
develocity-access-key: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
- name: Build project
run: ./gradlew build
```
### Maven
This workflow caches Maven dependencies through the Action.
```yaml
name: Artifact Cache Maven template
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v7
- name: Set up Java
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- name: Develocity Artifact Cache
uses: gradle/develocity-artifact-cache-github-action@v1
with:
develocity-url: https://develocity.example.com
develocity-access-key: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
- name: Build project
run: ./mvnw install
```
### npm
This workflow caches npm dependencies through the Action.
```yaml
name: Artifact Cache npm template
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v7
- name: Set up Java
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- name: Develocity Artifact Cache
uses: gradle/develocity-artifact-cache-github-action@v1
with:
develocity-url: https://develocity.example.com
develocity-access-key: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
- name: Build project
run: npm ci && npm run build
```
### Action Inputs
| Input | Required | Default | Description |
| --- | --- | --- | --- |
| `develocity-url` | One of | | Develocity server URL, passed to the CLI as `--dv-server`. |
| `develocity-edge-url` | One of | | Develocity Edge URL, passed to the CLI as `--dv-edge` to target an Edge directly instead of a server. |
| `develocity-access-key` | Yes | | Access key for the chosen endpoint host (`develocity-url` or `develocity-edge-url`) in `=` form (a bare key value is not accepted). The only key source; the `DEVELOCITY_ACCESS_KEY` environment variable and local key files are not read. Required to enable caching, but the Action warns and skips rather than failing the build when no key is found for the host. The Action exchanges it for a short-lived token used for its own cache restore and store and, when the CLI is downloaded from a Develocity Edge node, as the bearer credential for that download; the token is not exported to other steps. |
| `develocity-token-expiry` | No | `2` | Lifetime in hours of the short-lived token obtained from `develocity-access-key`, used for the Action’s own cache restore and store and, when the CLI is downloaded from a Develocity Edge node, as the bearer credential for that download. Raise it only if a build could run long enough for the token to expire before the post-step store. |
| `cli-version` | No | Pinned general-availability version | CLI version to download. |
| `image-names` | No | Auto-generated name (see [Automatic Image Name Generation](#automatic-image-name-generation)) | Ordered image names, one per line. The first is the primary; the rest are restore-only fallbacks. |
| `additional-cli-args` | No | | Extra arguments appended to every restore and store call, one per line, such as `--gradle-home=/home/runner/.gradle`. The flags the Action controls are rejected here. |
| `cache-read-only` | No | `false` | When `true`, skip the store step. |
| `cli-repository` | No | Public Develocity download URL, or a Develocity Edge node when `develocity-url` addresses one running version 2.3.0 or later | CLI download source. Set to an internal mirror for air-gapped runners; an explicit value here always wins over downloading from an Edge node. Must be an HTTPS URL unless `cli-repository-allow-insecure` is set. |
| `cli-repository-header` | No | | A single `Name: Value` HTTP header sent on the CLI download, for an authenticated mirror. Provide it through a secret so it is masked in logs. Ignored on the Edge node route, which authenticates with its own bearer token instead. |
| `cli-repository-allow-insecure` | No | `false` | Allow a `cli-repository` URL or a `develocity-url` used for the Edge node route to use plain HTTP; otherwise, an HTTP URL is rejected. Enable only for a trusted internal network without TLS: over HTTP, the download and its authentication credential (the `cli-repository-header` for a mirror or the short-lived bearer token for an Edge node) are sent without encryption. |
| `cli-sha256` | No | | Expected CLI SHA-256, needed only to verify a version the Action does not already ship a checksum for. |
### Air-Gapped and Custom CLI Hosting
By default the Action downloads the CLI from the public Develocity host. To serve the CLI from your own network, set `cli-repository` to your mirror. For an authenticated mirror, add `cli-repository-header` with a `Name: Value` header supplied through a secret:
```yaml
- name: Develocity Artifact Cache
uses: gradle/develocity-artifact-cache-github-action@v1
with:
develocity-url: https://develocity.example.com
cli-repository: https://mirror.example.com/artifact-cache-cli
cli-repository-header: ${{ secrets.MIRROR_AUTH_HEADER }}
```
## Automatic Image Name Generation
By default, Artifact Cache CLI generates an image name automatically when you do not set one explicitly. 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 do not have to choose or maintain a name yourself.
The Artifact Cache CLI inspects the following environment variables when generating image names for GitHub Runners:
* `GITHUB_WORKFLOW`
* `GITHUB_REF`
* `GITHUB_BASE_REF`
* `GITHUB_JOB`
* `GITHUB_ACTIONS`
* `RUNNER_ARCH`
* `RUNNER_OS`
On restore the Action also tries a fallback so a branch with no cache of its own can still restore from a related branch: a pull request falls back to its base branch’s cache, and a push or manually-dispatched run falls back to the repository’s default branch, so a new branch restores instead of starting cold.
### 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. With the GitHub Action, provide it through the `image-names` input. With the manual CLI setup, provide it with the `--image-name` CLI option.
### Matrix Builds
The auto-generated image name isolates caches per job and by the runner’s operating system and architecture. When a build matrix adds other axes, such as a Java or tool version, those jobs share one cache unless you isolate them.
With the GitHub Action, add a dedicated `image-names` entry to isolate a sensitive axis.
For example, in a job with a `strategy.matrix.java` axis, reference that axis in `image-names`. A custom `image-names` value replaces the auto-generated name entirely, so include the runner’s operating system and architecture (which the generated name isolates on) alongside the extra axis, and use a stable prefix to namespace the project:
```yaml
name: Develocity Artifact Cache
uses: gradle/develocity-artifact-cache-github-action@v1
with:
develocity-url: https://develocity.example.com
develocity-access-key: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
image-names: my-project-${{ runner.os }}-${{ runner.arch }}-java${{ matrix.java }}
```
Overriding the name also forgoes the automatic branch fallback described above, so prefer the generated name unless a matrix axis makes an override necessary.
## Manual CLI Setup
Use the manual setup when you cannot use the GitHub Action: on air-gapped or restricted-network runners, when your organization does not permit third-party GitHub Actions, or when you need control beyond the Action’s inputs. This approach downloads the CLI and runs the restore and store commands yourself.
For an air-gapped runner that can still use the Action, point the Action at an internal mirror with `cli-repository` instead (see [Air-Gapped and Custom CLI Hosting](#air-gapped)). Choose the manual setup when you also want to manage the restore and store steps yourself.
### Storing Credentials
In your GitHub repository settings, navigate to **Settings > Secrets and variables > Actions** and add:
| Secret Name | Value |
| --- | --- |
| `DEVELOCITY_ACCESS_KEY` | Your Develocity access key: `=` |
| `ARTIFACT_CACHE_REPO_USERNAME` | Your username for your internal artifact repository |
| `ARTIFACT_CACHE_REPO_PASSWORD` | Your password for your internal artifact repository |
> [!NOTE]
> If you use a custom internal artifact repository location, verify the "Provision and configure Artifact Cache" step. Ensure the `curl` command’s authentication parameters (`--user`) and download URL match your repository’s requirements.
### Gradle Project Setup
#### Configuration
Add these environment variables to your workflow:
```yaml
env:
# Artifact Cache CLI Configuration
ARTIFACT_CACHE_CLI_VERSION: 1.7.0
ARTIFACT_CACHE_IMAGE: my-gradle-project (1)
# Develocity Server
DV_SERVER: https://develocity.example.com (2)
# Authentication (from secrets)
DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
ARTIFACT_CACHE_REPO_USERNAME: ${{ secrets.ARTIFACT_CACHE_REPO_USERNAME }}
ARTIFACT_CACHE_REPO_PASSWORD: ${{ secrets.ARTIFACT_CACHE_REPO_PASSWORD }}
# Repository location - replace with your internal artifact repository URL
ARTIFACT_CACHE_REPO: https://your-internal-repo.example.com/path/to/artifact-cache-cli (3)
# CLI Configuration
ARTIFACT_CACHE_CLI_FILENAME: develocity-artifact-cache-cli
ARTIFACT_CACHE_OPTS: "--gradle-home=/home/runner/.gradle" (4)
```
1. Optional - leave unset for automatic generation (Recommended)
2. Replace with your Develocity server URL
3. Replace with the URL to your internal artifact repository where you’ve hosted the CLI binary
4. Assumes a Linux (Ubuntu) runner. macOS runners use /Users/runner, and Windows runners need the approach in Windows GitHub Runners. Also adjust for a custom Gradle User Home location.
#### Complete Workflow Example
```yaml
name: Artifact Cache CLI Gradle template
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
env:
# Artifact Cache Configuration
ARTIFACT_CACHE_CLI_VERSION: 1.7.0
# Develocity
DV_SERVER: https://
DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
# Artifact Cache CLI
ARTIFACT_CACHE_REPO_USERNAME: ${{ secrets.ARTIFACT_CACHE_REPO_USERNAME }}
ARTIFACT_CACHE_REPO_PASSWORD: ${{ secrets.ARTIFACT_CACHE_REPO_PASSWORD }}
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=/home/runner/.gradle"
steps:
- name: Checkout repository
uses: actions/checkout@v7
- name: Setup Java (Required for Artifact Cache)
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- name: Provision and configure Artifact Cache
shell: bash
run: |
TOOL_DIR="${{ runner.tool_cache }}/develocity/artifact-cache/${{ env.ARTIFACT_CACHE_CLI_VERSION }}"
JAR_PATH="$TOOL_DIR/${{ env.ARTIFACT_CACHE_CLI_FILENAME }}.jar"
mkdir -p "$TOOL_DIR"
# Download if not present
if [ ! -f "$JAR_PATH" ]; then
echo "Downloading Artifact Cache CLI v${{ env.ARTIFACT_CACHE_CLI_VERSION }}..."
curl --location --fail --silent --show-error \
--connect-timeout 5 --max-time 30 \
--retry 3 --retry-delay 3 --retry-max-time 60 \
--user "$ARTIFACT_CACHE_REPO_USERNAME:$ARTIFACT_CACHE_REPO_PASSWORD" \
"${{ 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 "$JAR_PATH"
fi
CMD="${{ env[format('JAVA_HOME_21_{0}', runner.arch)] }}/bin/java -jar $JAR_PATH"
echo "ARTIFACT_CACHE_CMD=$CMD" >> $GITHUB_ENV
CMD_OPTS="--dv-server=$DV_SERVER $ARTIFACT_CACHE_OPTS"
echo "ARTIFACT_CACHE_CMD_OPTS=$CMD_OPTS" >> $GITHUB_ENV
- name: Restore from Artifact Cache
id: restore_cache
run: $ARTIFACT_CACHE_CMD restore $ARTIFACT_CACHE_CMD_OPTS
- name: Warn on Cache Restore Failure
if: steps.restore_cache.outcome == 'failure'
run: 'echo "WARNING: Could not restore the Artifact Cache. The build will proceed but may be slower."'
- name: Build project
run: ./gradlew build
- name: Store to Artifact Cache
if: success()
id: store_cache
continue-on-error: true
run: $ARTIFACT_CACHE_CMD store $ARTIFACT_CACHE_CMD_OPTS
- name: Warn on Cache Store Failure
if: steps.store_cache.outcome == 'failure'
run: 'echo "WARNING: Failed to store in the Artifact Cache."'
- name: Persist Artifact Cache Logs
uses: actions/upload-artifact@v4
with:
name: artifact-cache.log
path: '~/.develocity/artifact-cache/artifact-cache.log'
retention-days: 7
```
#### Key Steps Explained
**Checkout Repository (First)** — Always checkout before restoring cache. This ensures the repository context is available for image name generation and allows the Setup Cache to restore shared build logic content into the project directory.
**Setup Java** — The Artifact Cache CLI requires Java 21. Use `actions/setup-java` with `java-version: 21`.
**Provision and Configure** — Downloads the Artifact Cache CLI JAR if not already cached in the runner’s tool cache. Sets up environment variables for subsequent steps.
**Restore from Artifact Cache** — Runs before the build to restore cached dependencies. Uses `continue-on-error` behavior via conditional warning.
**Store to Artifact Cache** — Runs after successful build to update the cache. Uses `if: success()` and `continue-on-error: true` to not fail the build if store fails.
**Persist Logs** — Uploads diagnostic logs for troubleshooting. Recommended for all workflows.
##### 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.6/gradle-plugin/) version 4.4.1 or later, and has the following constraints:
* The absolute project checkout path must remain constant across builds. GitHub Actions uses a stable path by default (`/home/runner/work//`).
* The repository checkout must happen before the `restore` command.
### Maven Project Setup
#### Configuration
```yaml
env:
# Change only these for Maven
ARTIFACT_CACHE_IMAGE: my-maven-project (1)
ARTIFACT_CACHE_OPTS: "--maven-home=/home/runner/.m2" (2)
```
1. Optional - leave unset for automatic generation (Recommended)
2. Assumes a Linux (Ubuntu) runner. macOS runners use /Users/runner, and Windows runners need the approach in Windows GitHub Runners. For a custom Maven repository, add --maven-repository=/custom/path.
#### Complete Workflow Example
```yaml
name: Artifact Cache CLI Maven template
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
env:
# Artifact Cache Configuration
ARTIFACT_CACHE_CLI_VERSION: 1.7.0
# Develocity
DV_SERVER: https://
DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
# Artifact Cache CLI
ARTIFACT_CACHE_REPO_USERNAME: ${{ secrets.ARTIFACT_CACHE_REPO_USERNAME }}
ARTIFACT_CACHE_REPO_PASSWORD: ${{ secrets.ARTIFACT_CACHE_REPO_PASSWORD }}
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=/home/runner/.m2"
steps:
- name: Checkout repository
uses: actions/checkout@v7
- name: Setup Java (Required for Artifact Cache)
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- name: Provision and configure Artifact Cache
shell: bash
run: |
TOOL_DIR="${{ runner.tool_cache }}/develocity/artifact-cache/${{ env.ARTIFACT_CACHE_CLI_VERSION }}"
JAR_PATH="$TOOL_DIR/${{ env.ARTIFACT_CACHE_CLI_FILENAME }}.jar"
mkdir -p "$TOOL_DIR"
# Download if not present
if [ ! -f "$JAR_PATH" ]; then
echo "Downloading Artifact Cache CLI v${{ env.ARTIFACT_CACHE_CLI_VERSION }}..."
curl --location --fail --silent --show-error \
--connect-timeout 5 --max-time 30 \
--retry 3 --retry-delay 3 --retry-max-time 60 \
--user "$ARTIFACT_CACHE_REPO_USERNAME:$ARTIFACT_CACHE_REPO_PASSWORD" \
"${{ 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 "$JAR_PATH"
fi
CMD="${{ env[format('JAVA_HOME_21_{0}', runner.arch)] }}/bin/java -jar $JAR_PATH"
echo "ARTIFACT_CACHE_CMD=$CMD" >> $GITHUB_ENV
CMD_OPTS="--dv-server=$DV_SERVER $ARTIFACT_CACHE_OPTS"
echo "ARTIFACT_CACHE_CMD_OPTS=$CMD_OPTS" >> $GITHUB_ENV
- name: Restore from Artifact Cache
id: restore_cache
run: $ARTIFACT_CACHE_CMD restore $ARTIFACT_CACHE_CMD_OPTS
- name: Warn on Cache Restore Failure
if: steps.restore_cache.outcome == 'failure'
run: 'echo "WARNING: Could not restore the Artifact Cache. The build will proceed but may be slower."'
- name: Build project
run: ./mvnw install
- name: Store to Artifact Cache
if: success()
id: store_cache
continue-on-error: true
run: $ARTIFACT_CACHE_CMD store $ARTIFACT_CACHE_CMD_OPTS
- name: Warn on Cache Store Failure
if: steps.store_cache.outcome == 'failure'
run: 'echo "WARNING: Failed to store in the Artifact Cache."'
- name: Persist Artifact Cache Logs
uses: actions/upload-artifact@v4
with:
name: artifact-cache.log
path: '~/.develocity/artifact-cache/artifact-cache.log'
retention-days: 7
```
#### 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:
```yaml
env:
ARTIFACT_CACHE_OPTS: "--maven-home=/home/runner/.m2 --maven-repository=/custom/repo"
```
### npm Project Setup
#### Configuration
```yaml
env:
# Change only these for npm
ARTIFACT_CACHE_IMAGE: my-npm-project (1)
ARTIFACT_CACHE_OPTS: "--npm-home=/home/runner/.npm" (2)
```
1. Optional - leave unset for automatic generation (Recommended)
2. Assumes a Linux (Ubuntu) runner. macOS runners use /Users/runner, and Windows runners need the approach in Windows GitHub Runners.
#### Complete Workflow Example
```yaml
name: Artifact Cache CLI npm template
on:
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
env:
# Artifact Cache Configuration
ARTIFACT_CACHE_CLI_VERSION: 1.7.0
# Develocity
DV_SERVER: https://
DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
# Artifact Cache CLI
ARTIFACT_CACHE_REPO_USERNAME: ${{ secrets.ARTIFACT_CACHE_REPO_USERNAME }}
ARTIFACT_CACHE_REPO_PASSWORD: ${{ secrets.ARTIFACT_CACHE_REPO_PASSWORD }}
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=/home/runner/.npm"
steps:
- name: Checkout repository
uses: actions/checkout@v7
- name: Setup Java (Required for Artifact Cache)
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: 21
- name: Provision and configure Artifact Cache
shell: bash
run: |
TOOL_DIR="${{ runner.tool_cache }}/develocity/artifact-cache/${{ env.ARTIFACT_CACHE_CLI_VERSION }}"
JAR_PATH="$TOOL_DIR/${{ env.ARTIFACT_CACHE_CLI_FILENAME }}.jar"
mkdir -p "$TOOL_DIR"
# Download if not present
if [ ! -f "$JAR_PATH" ]; then
echo "Downloading Artifact Cache CLI v${{ env.ARTIFACT_CACHE_CLI_VERSION }}..."
curl --location --fail --silent --show-error \
--connect-timeout 5 --max-time 30 \
--retry 3 --retry-delay 3 --retry-max-time 60 \
--user "$ARTIFACT_CACHE_REPO_USERNAME:$ARTIFACT_CACHE_REPO_PASSWORD" \
"${{ 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 "$JAR_PATH"
fi
CMD="${{ env[format('JAVA_HOME_21_{0}', runner.arch)] }}/bin/java -jar $JAR_PATH"
echo "ARTIFACT_CACHE_CMD=$CMD" >> $GITHUB_ENV
CMD_OPTS="--dv-server=$DV_SERVER $ARTIFACT_CACHE_OPTS"
echo "ARTIFACT_CACHE_CMD_OPTS=$CMD_OPTS" >> $GITHUB_ENV
- name: Restore from Artifact Cache
id: restore_cache
run: $ARTIFACT_CACHE_CMD restore $ARTIFACT_CACHE_CMD_OPTS
- name: Warn on Cache Restore Failure
if: steps.restore_cache.outcome == 'failure'
run: 'echo "WARNING: Could not restore the Artifact Cache. The build will proceed but may be slower."'
- name: Build project
run: npm ci && npm run build
- name: Store to Artifact Cache
if: success()
id: store_cache
continue-on-error: true
run: $ARTIFACT_CACHE_CMD store $ARTIFACT_CACHE_CMD_OPTS
- name: Warn on Cache Store Failure
if: steps.store_cache.outcome == 'failure'
run: 'echo "WARNING: Failed to store in the Artifact Cache."'
- name: Persist Artifact Cache Logs
uses: actions/upload-artifact@v4
with:
name: artifact-cache.log
path: '~/.develocity/artifact-cache/artifact-cache.log'
retention-days: 7
```
## 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.
If your workflow caches `~/.sonar` or `~/.sonar/cache` via `actions/cache`, remove that step. The Artifact Cache CLI handles SonarScanner caching automatically.
> [!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 the CLI arguments. With the GitHub Action, add it to `additional-cli-args`; with the manual setup, add it to `ARTIFACT_CACHE_OPTS`:
```yaml
env:
ARTIFACT_CACHE_OPTS: "--gradle-home=/home/runner/.gradle --sonar-home=/home/runner/.sonar"
```
To opt out of SonarScanner caching even when the user home is present, exclude it from auto-detection:
```yaml
env:
ARTIFACT_CACHE_OPTS: "--gradle-home=/home/runner/.gradle --no-autodetect=SONAR"
```
## Windows GitHub Runners
Windows runners require additional configuration due to path handling differences.
```yaml
- name: Set Dynamic Environment Variables
shell: bash
run: |
NORMALIZED_TOOL_PATH=$(echo "${{ runner.tool_cache }}" | sed 's|\\|/|g' | sed 's|^C:/|/c/|i')
echo "DV_ARTIFACT_CACHE_JAR_PATH=$NORMALIZED_TOOL_PATH/develocity/${{ env.DV_ARTIFACT_CACHE_CLI_VERSION }}/develocity-artifact-cache-cli.jar" >> $GITHUB_ENV
echo "DV_CACHE_DIR=$HOME/.gradle" >> $GITHUB_ENV
NORMALIZED_JAVA_PATH=$(echo "${{ env[format('JAVA_HOME_21_{0}', runner.arch)] }}" | sed 's|\\|/|g' | sed 's|^C:/|/c/|i')
echo "DV_JAVA=$NORMALIZED_JAVA_PATH/bin/java" >> $GITHUB_ENV
#...
- name: Restore Artifact Cache
id: restore_cache
shell: bash
run: |
$DV_JAVA -jar "${{ env.DV_ARTIFACT_CACHE_JAR_PATH }}" \
restore \
--server="${{ env.DV_SERVER }}" \
--image-name="${{ env.DV_ARTIFACT_CACHE_IMAGE }}" \
--gradle-home="${{ env.DV_CACHE_DIR }}"
```
## Related Documentation
* [CLI Commands Reference](https://docs.develocity.ai/artifact-cache/1.7/reference/cli-commands/)
* [Workload Identity](https://docs.develocity.ai/2026.3/administration/access-control/workload-identity/) (configuring Develocity to accept OIDC tokens)
* [Develocity Artifact Cache GitHub Action README](https://github.com/gradle/develocity-artifact-cache-github-action#readme) (supported runners, versioning, and access-key resolution in detail)