GitHub Actions で Go モジュールとビルドキャッシュをキャッシュする
最終更新
Go のキャッシュを GitHub Actions で行うには、actions/setup-go を使用します。デフォルトで Go モジュールとビルド出力をキャッシュし、キーは go.sum に基づきます。有用なキャッシュは 2 種類あります。モジュールキャッシュ (GOMODCACHE、ダウンロード済みの依存関係) とビルドキャッシュ (GOCACHE、コンパイル済みのパッケージとテスト結果) です。組み込みのキャッシュは両方を対象とします。
方法 1: setup-go
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-go@v7
with:
go-version-file: go.mod
cache-dependency-path: go.sum
- run: go build ./...
- run: go test ./...
setup-go の README(2026 年 10 月確認)によると、cache の既定値は true で、Go モジュールとビルド出力をキャッシュします。既定の依存関係ファイルはリポジトリルートの go.mod です。チェックサムファイルをキーにする場合は cache-dependency-path に go.sum を指定し、複数のモジュールがある場合はグロブを指定します。
- uses: actions/setup-go@v7
with:
go-version-file: go.mod
cache-dependency-path: |
go.sum
tools/go.sum
リリースを公開するワークフローなどでは、cache: false を指定して無効にできます。
方法2: 明示的なactions/cache
OS ごとに正しいパスを使えるよう、Go にキャッシュの場所を確認します。
- uses: actions/setup-go@v7
with:
go-version-file: go.mod
cache: false
- name: Find Go cache paths
id: go-cache
run: |
echo "mod=$(go env GOMODCACHE)" >> "$GITHUB_OUTPUT"
echo "build=$(go env GOCACHE)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
with:
path: |
${{ steps.go-cache.outputs.mod }}
${{ steps.go-cache.outputs.build }}
key: go-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/go.sum') }}
restore-keys: |
go-${{ runner.os }}-${{ runner.arch }}-
- run: go test ./...
Linux では ~/go/pkg/mod と ~/.cache/go-build になります。cache: false を設定すると、キャッシュが重複するのを防げます。
2 つのキャッシュ、2 つの役割
モジュールキャッシュは go.sum をキーにすると適切に管理できます。チェックサムに記載されたものがそのまま含まれるためです。一方、ビルドキャッシュは性質が異なります。Go のビルドキャッシュはコンテンツアドレス方式で、ソース、コンパイラフラグ、依存関係のハッシュが一致する場合にのみエントリが有効になります。そのため、前日のコミットから復元したビルドキャッシュの大部分はそのまま有効で、Go は変更された部分だけを再ビルドします。
そのため、restore-keys によるプレフィックスのフォールバックは、GOCACHE に特に有効です。go.sum が変更されても、コンパイル済みのパッケージの大部分は無効になりません。古いエントリがあっても、Go がコンテンツのハッシュを検証するため問題ありません。
| キャッシュ | 内容 | 短縮効果 | キー |
|---|---|---|---|
GOMODCACHE | ダウンロード済みモジュールのソース | ネットワーク時間 | go.sum |
GOCACHE | コンパイル済みパッケージ、テスト結果 | コンパイルとテストの時間 | go.sum + プレフィックスのフォールバック |
GOCACHE のテスト結果は有効です。入力が変更されていないパッケージについては、go test が (cached) と表示します。CI では、同じフラグを使用している場合に限り、パッケージ単位でテストを省略できます。-race を付けたビルドは通常のビルドとは別のキャッシュエントリを使用する点にご注意ください。また、-count=1 を指定するとテスト結果のキャッシュが無効になります。毎回新しい結果が必要な場合は、その分の時間がかかることを想定してください。
キャッシュ以外の高速化
go mod downloadを個別のステップとして実行すると、依存関係の処理時間をログで確認できます。go test -raceは設計上、実行が遅くなります(多くの場合 2〜10 倍)。compiler.dev で React、Go、Postgres をgo test -raceで計測した実行では、CI 時間は 6 分 13 秒から 2 分 42 秒に短縮されました。主な要因は CPU を増強したことです(ベンチマークを参照)。- テストのシャーディングでパッケージを複数のジョブに分割できます。Go の
go list ./...は自然な分割に役立ちます。 -pはビルドの並列数を制御します。既定値は GOMAXPROCS で、CPU コア数に応じて決まります。- 大規模なリポジトリでは、すべてを 10 GB の GitHub キャッシュに保存するのではなく、リモートキャッシュ(最近の Go バージョンでは GOCACHEPROG をサポート)の利用を検討してください。
キャッシュヒットの確認方法
- setup-go ステップは、キャッシュがヒットすると
Cache restored from key: setup-go-Linux-...を、ミスするとCache not foundをログに出力します。post ステップはCache savedをログに出力します。 - ローカルまたはデバッグ用のジョブで
go build -xを実行してください。復元されたパッケージは再コンパイルされません。go testは、変更のないパッケージに対して(cached)を表示します。 GOMODCACHEが温まっている場合、go mod downloadは 1 秒を大きく下回って完了するはずです。gh cache list --key setup-go --limit 20でサイズと最終使用日時を確認できます。
よくある間違い
- モジュールグラフが
go.sumに記録されている場合は、go.modをハッシュします。 ほとんどのリポジトリでは両者は同時に変更されますが、go.sum はチェックサムの記録であるため、明示的なキャッシュではこれをキーにします。 - ベンダリングされたリポジトリのキャッシュ。
go mod vendorの結果をコミットしている場合、キャッシュ対象となるモジュールのダウンロードはありません。キャッシュするのはGOCACHEのみです。 GOPATH/binのキャッシュ。go installでインストールしたツールは、ツールのバージョンをキーにする必要があります。- 1 つのキーに複数の Go バージョン。 ビルドキャッシュは内部的に Go のバージョンごとに分けられますが、1 つのエントリにまとめると容量が無駄になります。マトリクスでは、キーにバージョンを含めてください。
- PR のときのみ保存。
mainからキャッシュを作成してください。GitHub Actions のキャッシュを参照してください。
よくある質問
setup-go は既定でキャッシュしますか?
はい。cache 入力の既定値は true です。無効にするには cache: false を設定してください。
GOCACHEとモジュールの両方をキャッシュすべきですか?
両方をおすすめします。モジュールのダウンロードは通信環境が良ければ速く終わりますが、時間がかかるのはコンパイルです。GOCACHEはそのコンパイル時間を削減します。
go testが毎回実行されるのはなぜですか?
テストキャッシュは、-count=1を指定したとき、変更されたファイルやテストが読み取る環境変数があるとき、モジュール外のファイルを開くテストでは使われません。コマンドに-count=1が含まれていないか確認してください。
Goのキャッシュはどのくらいの大きさになりますか?
通常は数百MBです。CGoを使用する場合やテストバイナリが多い場合はさらに大きくなります。キャッシュの上限をご覧ください。
次のステップ
あわせてGoのCIを全体的に高速化する方法もご覧ください。Cargoにも同様の仕組みがあり、Rustのビルドをキャッシュする方法で解説しています。全体のチェックリストはGitHub Actionsを高速化する方法をご覧ください。compiler.devでは同じジョブを8 vCPUで1分あたり$0.008で実行できます。料金をご確認ください。
関連記事
- GitHub Actions で Cargo と Rust のビルドをキャッシュするSwatinem/rust-cache または actions/cache を使用して、GitHub Actions で Cargo レジストリ、git 依存関係、target ディレクトリをキャッシュします。キャッシュが肥大化しないように注意します。
- GitHub Actions で Gradle ビルドをキャッシュするgradle/actions/setup-gradle または actions/cache を使用して、GitHub Actions で Gradle の依存関係とビルドキャッシュをキャッシュします。キー、プルリクエストでの読み取り専用設定、クリーンアップ、確認方法を解説します。
- GitHub Actions で npm の依存関係をキャッシュするsetup-node または actions/cache を使用して、GitHub Actions で npm の依存関係をキャッシュします。動作する YAML、適切なキー、node_modules をキャッシュしない理由、キャッシュヒットの確認方法を解説します。
- GitHub Actionsでpipの依存関係をキャッシュするsetup-python または actions/cache を使って GitHub Actions で pip をキャッシュします。より高速な uv の選択肢もあります。キーの設計、キャッシュすべきでないもの、キャッシュヒットの確認方法を解説します。