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へ公開または読み取る場合のみ |
キャッシュヒットの確認方法
- ジョブページのsetup-gradleステップのサマリーには、復元および保存されたキャッシュエントリとそのサイズが表示されます。
- Gradleの出力で、タスクの横にある
FROM-CACHEは、その出力がビルドキャッシュから取得されたことを示します。UP-TO-DATEは、ローカルで変更がないことを意味します。 - キャッシュが温まった状態の実行では、
--infoの出力に依存関係のダウンロードが表示されないはずです。 gh cache list --key gradle --limit 20で、エントリと最終使用日時を確認できます。
よくある間違い
- mainにキャッシュが作成されない。ブランチが読み取り専用の場合、デフォルトブランチでのビルドが実行されるまで何も保存されません。
- setupアクションより前にGradleを実行している。必ずアクションを最初に配置してください。
- 手動キーでのハッシュ対象が少なすぎる問題です。バージョンカタログとラッパーのプロパティを含めてください。
build/をキャッシュすることの問題です。サイズが大きく、コミットごとに一致しなくなります。- サイズを無視することの問題です。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の料金をご覧ください。
関連記事
- GitHub Actions で Cargo と Rust のビルドをキャッシュするSwatinem/rust-cache または actions/cache を使用して、GitHub Actions で Cargo レジストリ、git 依存関係、target ディレクトリをキャッシュします。キャッシュが肥大化しないように注意します。
- GitHub Actions で Go モジュールとビルドキャッシュをキャッシュするsetup-go または actions/cache を使用して、GitHub Actions で Go モジュール(GOMODCACHE)とビルドキャッシュ(GOCACHE)をキャッシュします。キー、go.sum、キャッシュヒットの確認方法を解説します。
- GitHub Actions で npm の依存関係をキャッシュするsetup-node または actions/cache を使用して、GitHub Actions で npm の依存関係をキャッシュします。動作する YAML、適切なキー、node_modules をキャッシュしない理由、キャッシュヒットの確認方法を解説します。
- GitHub Actionsでpipの依存関係をキャッシュするsetup-python または actions/cache を使って GitHub Actions で pip をキャッシュします。より高速な uv の選択肢もあります。キーの設計、キャッシュすべきでないもの、キャッシュヒットの確認方法を解説します。