Configuring GitHub Actions

This guide shows you how to integrate the Artifact Cache CLI into your GitHub Actions workflows.

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

  • Artifact Cache CLI repository credentials

See System Requirements for complete details.

Disable 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)

Disable caching by setting cache-disabled: true.

Setup Java (actions/setup-java)

Do not enable caching - omit the cache parameter.

Cache Action (actions/cache)

Do not use for Gradle or Maven dependencies. See examples for what to avoid.

Store Secrets

In your GitHub repository settings, navigate to Settings > Secrets and variables > Actions and add:

Secret Name Value

DEVELOCITY_ACCESS_KEY

Your Develocity access key: <hostname>=<key_value>

ARTIFACT_CACHE_REPO_USERNAME

Your username for gradlecom.jfrog.io

ARTIFACT_CACHE_REPO_PASSWORD

Your password for gradlecom.jfrog.io

Gradle Project Setup

Configuration

Add these environment variables to your workflow:

env: # Artifact Cache CLI Configuration ARTIFACT_CACHE_CLI_VERSION: 0.10.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 ARTIFACT_CACHE_REPO: https://gradlecom.jfrog.io/artifactory/develocity-artifact-cache-cli-libs-releases-local # CLI Configuration ARTIFACT_CACHE_CLI_FILENAME: develocity-artifact-cache-cli ARTIFACT_CACHE_OPTS: "--gradle-home=/home/runner/.gradle" # <3>
1 Optional - leave unset for automatic generation
2 Replace with your Develocity server URL
3 Adjust if using a custom Gradle User Home location

Complete Workflow Example

name: Artifact Cache CLI Gradle template

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      # Artifact Cache Configuration
      ARTIFACT_CACHE_CLI_VERSION: 0.10.0
      ARTIFACT_CACHE_IMAGE: sample-gradle
      # Develocity
      DV_SERVER: https://<develocity.address>
      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://gradlecom.jfrog.io/artifactory/develocity-artifact-cache-cli-libs-releases-local
      # Misc
      ARTIFACT_CACHE_CLI_FILENAME: develocity-artifact-cache-cli
      ARTIFACT_CACHE_OPTS: "--gradle-home=/home/runner/.gradle"
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - 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_IMAGE:+--image-name=$ARTIFACT_CACHE_IMAGE} $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.

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.

Maven Project Setup

Configuration

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
2 For custom Maven repository, add: --maven-repository=/custom/path

Complete Workflow Example

name: Artifact Cache CLI Maven template

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      # Artifact Cache Configuration
      ARTIFACT_CACHE_CLI_VERSION: 0.10.0
      ARTIFACT_CACHE_IMAGE: sample-maven
      # Develocity
      DV_SERVER: https://<develocity.address>
      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://gradlecom.jfrog.io/artifactory/develocity-artifact-cache-cli-libs-releases-local
      # Misc
      ARTIFACT_CACHE_CLI_FILENAME: develocity-artifact-cache-cli
      ARTIFACT_CACHE_OPTS: "--maven-home=/home/runner/.m2"
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - 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_IMAGE:+--image-name=$ARTIFACT_CACHE_IMAGE} $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:

env:
  ARTIFACT_CACHE_OPTS: "--maven-home=/home/runner/.m2 --maven-repository=/custom/repo"

npm Project Setup

Configuration

env:
  # Change only these for npm
  ARTIFACT_CACHE_IMAGE: my-npm-project (1)
  ARTIFACT_CACHE_OPTS: "--npm-home=/home/runner/.npm"
1 Optional - leave unset for automatic generation

Complete Workflow Example

name: Artifact Cache CLI npm template

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      # Artifact Cache Configuration
      ARTIFACT_CACHE_CLI_VERSION: 0.10.0
      ARTIFACT_CACHE_IMAGE: sample-npm
      # Develocity
      DV_SERVER: https://<develocity.address>
      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://gradlecom.jfrog.io/artifactory/develocity-artifact-cache-cli-libs-releases-local
      # Misc
      ARTIFACT_CACHE_CLI_FILENAME: develocity-artifact-cache-cli
      ARTIFACT_CACHE_OPTS: "--npm-home=/home/runner/.npm"
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - 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_IMAGE:+--image-name=$ARTIFACT_CACHE_IMAGE} $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

Windows GitHub Runners

Windows runners require additional configuration due to path handling differences.

- 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 }}"