Cache Java/Maven/Gradle dans GitHub Actions

Les projets Java ont souvent des dépendances volumineuses. Un build Maven ou Gradle sans cache peut télécharger des centaines de Mo de JARs. Le cache réduit ce temps de plusieurs minutes à quelques secondes.

Ce que vous allez apprendre

Activer le cache intégré de setup-java pour Maven et Gradle
Configurer actions/cache pour un contrôle fin des dépôts locaux
Utiliser gradle/actions/setup-gradle, l'action officielle Gradle
Construire un workflow complet Maven ou Gradle, matriciel
Gérer les multi-modules et déboguer un cache corrompu

Cache intégré avec setup-java

La méthode recommandée utilise le cache intégré :

- uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
  with:
    distribution: 'temurin'
    java-version: '21'
    cache: 'maven'  # ou 'gradle'

- run: mvn verify

Options de cache

Valeur	Gestionnaire
`maven`	Maven (détecte `pom.xml`)
`gradle`	Gradle (détecte `build.gradle` ou `build.gradle.kts`)
`sbt`	SBT (détecte `build.sbt`)

Cache Maven manuel

Pour plus de contrôle :

- uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
  with:
    distribution: 'temurin'
    java-version: '21'

- name: Cache Maven packages
  uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
  with:
    path: ~/.m2/repository
    key: maven-${{ runner.os }}-${{ hashFiles('**/pom.xml') }}
    restore-keys: |
      maven-${{ runner.os }}-

- run: mvn verify

Cache avec wrapper Maven

- name: Cache Maven
  uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
  with:
    path: |
      ~/.m2/repository
      ~/.m2/wrapper
    key: maven-${{ runner.os }}-${{ hashFiles('**/pom.xml', '**/maven-wrapper.properties') }}
    restore-keys: |
      maven-${{ runner.os }}-

Cache Gradle manuel

Si vous n'utilisez pas l'action officielle Gradle, cachez à la main les dépendances et le wrapper Gradle.

- uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
  with:
    distribution: 'temurin'
    java-version: '21'

- name: Cache Gradle
  uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
    key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
    restore-keys: |
      gradle-${{ runner.os }}-

- run: ./gradlew build

Cache du build Gradle

Pour cacher aussi les résultats de compilation :

- uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
      .gradle
      build
    key: gradle-build-${{ runner.os }}-${{ github.sha }}
    restore-keys: |
      gradle-build-${{ runner.os }}-
      gradle-${{ runner.os }}-

Action gradle/actions (recommandé)

L'action officielle Gradle gère automatiquement le cache :

- uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
  with:
    distribution: 'temurin'
    java-version: '21'

- name: Setup Gradle
  uses: gradle/actions/setup-gradle@06832c7b30a0129d7fb559bcc6e43d26f6374244 # v4.3.1

- run: ./gradlew build

Cette action :

Cache automatiquement les dépendances Gradle
Génère un rapport de build
Supporte le build scan

Workflow complet Maven

name: Java CI with Maven

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions: {}

jobs:
  build:
    runs-on: ubuntu-24.04
    permissions:
      contents: read

    strategy:
      matrix:
        java: [17, 21]

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

      - name: Setup Java ${{ matrix.java }}
        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
        with:
          distribution: 'temurin'
          java-version: ${{ matrix.java }}
          cache: 'maven'

      - name: Build and test
        run: mvn -B verify

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: test-results-java${{ matrix.java }}
          path: target/surefire-reports/

Workflow complet Gradle

name: Java CI with Gradle

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions: {}

jobs:
  build:
    runs-on: ubuntu-24.04
    permissions:
      contents: read

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

      - name: Setup Java
        uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
        with:
          distribution: 'temurin'
          java-version: '21'

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@06832c7b30a0129d7fb559bcc6e43d26f6374244 # v4.3.1

      - name: Build
        run: ./gradlew build

      - name: Test
        run: ./gradlew test

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: test-results
          path: build/reports/tests/

Optimisations spécifiques

Au-delà du cache, quelques options accélèrent encore les builds Java — incrémental, parallélisme, tests conditionnels.

Build incrémental Gradle

- name: Build with incremental
  run: ./gradlew build --build-cache

Tests en parallèle

# Maven
- run: mvn -B verify -T 4  # 4 threads

# Gradle
- run: ./gradlew test --parallel

Skip les tests optionnellement

- name: Build
  run: mvn -B package ${{ github.event_name == 'push' && '' || '-DskipTests' }}

Multi-modules Maven

Sur un projet multi-modules, ne reconstruisez que les modules réellement modifiés : le cache des dépendances reste partagé, le build cible le strict nécessaire.

- name: Cache Maven modules
  uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3
  with:
    path: ~/.m2/repository
    key: maven-${{ runner.os }}-${{ hashFiles('**/pom.xml') }}
    restore-keys: |
      maven-${{ runner.os }}-

# Build uniquement les modules modifiés
- name: Build changed modules
  run: |
    MODULES=$(git diff --name-only HEAD~1 | grep pom.xml | xargs dirname | tr '\n' ',')
    if [ -n "$MODULES" ]; then
      mvn -B -pl "$MODULES" -am verify
    fi

Erreurs courantes

Trois problèmes typiques touchent les builds Java en CI. Voici leur symptôme et la correction.

Cache corrompu

# Symptôme : erreurs de checksum
Could not resolve dependencies for project

# Solution : supprimer le cache
gh cache delete maven-linux-* --repo owner/repo

Gradle daemon issues

# Désactiver le daemon dans CI
- run: ./gradlew build --no-daemon

Settings.xml avec credentials

- uses: actions/setup-java@c5195efecf7bdfc987ee8bae7a71cb8b11521c00 # v4.7.1
  with:
    distribution: 'temurin'
    java-version: '21'
    cache: 'maven'
    server-id: github
    server-username: MAVEN_USERNAME
    server-password: MAVEN_TOKEN

- run: mvn deploy
  env:
    MAVEN_USERNAME: ${{ github.actor }}
    MAVEN_TOKEN: ${{ secrets.GITHUB_TOKEN }}

À retenir

Le cache intégré de setup-java (cache: 'maven' / 'gradle' / 'sbt') est la méthode recommandée.
actions/cache manuel donne le contrôle des chemins (~/.m2/repository, ~/.gradle/caches) quand le cache intégré ne suffit pas.
Pour Gradle, gradle/actions/setup-gradle gère le cache automatiquement et ajoute un rapport de build.
Désactivez le daemon Gradle en CI (--no-daemon) : il n'apporte rien sur un runner éphémère.
Un cache corrompu se purge avec gh cache delete — pensez-y face à des erreurs de checksum.

Prochaines étapes

Accélérer avec le cache Le guide général : clés, restore-keys, sécurité

Cache Node.js Stratégies de cache pour npm, yarn et pnpm

Cache Python Cacher pip et Poetry efficacement

Optimiser les workflows Vue d'ensemble des techniques d'optimisation