コンテンツへスキップ

GitHub Actions で Gradle ビルドをキャッシュする

最終更新

GitHub ActionsでGradleをキャッシュするには、gradle/actions/setup-gradleを使用します。Gradle User Home(依存関係、ラッパー、ビルドキャッシュ)をキャッシュし、キーの管理、クリーンアップ、読み取り専用の動作を自動で処理します。~/.gradle/cachesに対してactions/cacheを手動で記述する方法も使えますが、上記の機能の多くは含まれません。

オプション1:setup-gradle

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: 21
      - uses: gradle/actions/setup-gradle@v6
      - run: ./gradlew build

設定はこれだけです。アクションの後でラッパー(./gradlew)を使ってGradleを実行してください。アクションのキャッシュはジョブの終了時に保存されるためです。actions/cacheやkeyは必要ありません。

setup-gradleのドキュメント(2026年10月確認)によると、このアクションがキャッシュする内容は次のとおりです。デフォルトでは、Gradle User Home内のcachesサブディレクトリを対象とする拡張キャッシュを使用します。ダウンロードされた依存関係(modules-2)、トランスフォーム、生成されたjar、Kotlin DSLスクリプトのキャッシュ、ローカルのビルドキャッシュ、そしてラッパーの配布物が含まれます。基本モードでは、~/.gradle/cachesと~/.gradle/wrapperのみをキャッシュします。

ブランチでは読み取り専用、mainでは書き込み

デフォルトでは、デフォルトブランチのジョブのみがキャッシュに書き込みます。その他のブランチのジョブは既存のキャッシュを読み取るだけで、保存は行いません。これにより、プルリクエストによって10 GBの上限が近似的な重複エントリで埋まるのを防ぎます。また、キャッシュを作成するにはmainでGradleビルドを実行する必要があります。

- uses: gradle/actions/setup-gradle@v6
  with:
    cache-read-only: ${{ github.ref != 'refs/heads/main' }}

この式はデフォルトの動作であり、変更できるように示しています。たとえば、リリースブランチにも書き込ませることができます。ドキュメントでは、ブランチ式を含めてcache-read-onlyで上書きする方法が説明されています。

クリーンアップ

cache-cleanupは、キャッシュを保存する前に、Gradle User Homeから未使用のファイルを削除します。値はon-success(デフォルト)、always、neverです。キャッシュが読み取り専用または無効の場合は実行されません。デフォルトのままにしておくことをお勧めします。これがないと、プロジェクトが過去に使用したすべての依存関係のすべてのバージョンがキャッシュに蓄積されてしまいます。

構成キャッシュの暗号化

Gradleの構成キャッシュを使用する場合、エントリにシークレットが含まれることがあります。setup-gradleはcache-encryption-key(base64のAESキー。openssl rand -base64 16で生成し、シークレットとして保存できます)を受け取り、GitHubのキャッシュ内でエントリを暗号化します。

方法2: 明示的なactions/cache

- uses: actions/cache@v6
  with:
    path: |
      ~/.gradle/caches
      ~/.gradle/wrapper
    key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties', '**/libs.versions.toml') }}
    restore-keys: |
      gradle-${{ runner.os }}-

サードパーティがホストするアクションを避ける必要がある場合はこちらを使用してください。ただし、gradle/actionsはGradleプロジェクトによって保守されています。この方法では、自動クリーンアップ、ブランチを考慮した読み取り専用モード、ジョブごとのキーは利用できません。クリーンアップがないと、restore-keysは古いエントリの上に新しいエントリを重ね続け、削除されるまでキャッシュが増え続けます。

Gradleのビルドキャッシュとリモートキャッシュ

関係するキャッシュは2種類あります。

  • 依存関係キャッシュ(modules-2):ダウンロードされたjarです。上記の両方のオプションで処理されます。
  • ビルドキャッシュ:入力が一致したときに再利用されるタスクの出力です。gradle.propertiesでorg.gradle.caching=trueを設定するか、--build-cacheを指定して有効にします。setup-gradleはローカルのビルドキャッシュをGitHubのキャッシュ内に保存するため、プルリクエストはmainのコンパイルおよびテストの出力を再利用できます。

大規模なチームでは、リモートのビルドキャッシュノード(Develocityまたはセルフホストのbuild-cache-node)を使用できます。これはジョブや開発者間で共有され、GitHubの10 GBの上限にも制限されません。設定方法については、Gradleのビルドキャッシュのドキュメントをご覧ください。

また、org.gradle.parallel=trueを追加し、org.gradle.workers.maxを確認してください。GradleはデフォルトでCPUコア数を使用するため、より大きなマシンを使うと設定を変更せずに高速化できます。compiler.devの計測ベンチマークでは、Angular、Spring Boot(Gradle)、PostgreSQLを使ったCI実行が、GitHubホステッドランナーで6分57秒かかっていたのに対し、2分18秒に短縮されました(ベンチマークを参照)。

キャッシュすべきものとすべきでないもの

パスキャッシュするか備考
~/.gradle/cachesあり依存関係とビルドキャッシュ
~/.gradle/wrapperありGradleの配布物。実行のたびにダウンロードするのを避けられます
プロジェクト内の.gradle/注意が必要構成キャッシュのデータを保持します。setup-gradleが処理します
build/ディレクトリなし代わりにビルドキャッシュを使用してください。出力には絶対パスが埋め込まれます
~/.m2別扱いMaven localへ公開または読み取る場合のみ

キャッシュヒットの確認方法

  1. ジョブページのsetup-gradleステップのサマリーには、復元および保存されたキャッシュエントリとそのサイズが表示されます。
  2. Gradleの出力で、タスクの横にあるFROM-CACHEは、その出力がビルドキャッシュから取得されたことを示します。UP-TO-DATEは、ローカルで変更がないことを意味します。
  3. キャッシュが温まった状態の実行では、--infoの出力に依存関係のダウンロードが表示されないはずです。
  4. gh cache list --key gradle --limit 20で、エントリと最終使用日時を確認できます。

よくある間違い

  1. mainにキャッシュが作成されない。ブランチが読み取り専用の場合、デフォルトブランチでのビルドが実行されるまで何も保存されません。
  2. setupアクションより前にGradleを実行している。必ずアクションを最初に配置してください。
  3. 手動キーでのハッシュ対象が少なすぎる問題です。バージョンカタログとラッパーのプロパティを含めてください。
  4. build/をキャッシュすることの問題です。サイズが大きく、コミットごとに一致しなくなります。
  5. サイズを無視することの問題です。Androidやマルチモジュールのビルドでは、キャッシュが数GBに膨らみます。キャッシュの上限をご確認ください。

よくある質問

setup-gradleを使う場合も、actions/cacheは必要ですか?

いいえ。Gradle User Homeについては、setup-gradleがactions/cacheを置き換えます。NodeやDockerなど、ほかの用途にはactions/cacheを引き続きお使いください。

Mavenでも使えますか?

setup-gradleはGradle専用です。Mavenの場合は、actions/setup-javaとcache: mavenを使って~/.m2/repositoryをキャッシュするか、**/pom.xmlをキーにしたactions/cacheをお使いください。

キャッシュを使っていても、最初のPRのビルドが遅いのはなぜですか?

mainでまだキャッシュが作成されていない場合、またはキャッシュが削除された場合、PRはキャッシュなしで始まります。mainでビルドを実行してください。

CIでGradleデーモンを使えますか?

新しいジョブでは、いずれにしても新しいデーモンが起動します。setup-gradleには適切な初期設定が含まれているため、通常は変更する必要はありません。

次のステップ

関連ページ:Gradleビルドをエンドツーエンドで高速化する方法、Gradleビルドでイメージを作成する場合はDockerレイヤーのキャッシュ、そしてGitHub Actionsを高速化する方法です。同じビルドを8 vCPUのマシンで試すには、compiler.devの料金をご覧ください。

このGradleビルドをcompiler.devで実行 カード登録不要 · 200 無料分

無料で試す