コンテンツへスキップ

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 をサポート)の利用を検討してください。

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

  1. setup-go ステップは、キャッシュがヒットすると Cache restored from key: setup-go-Linux-... を、ミスすると Cache not found をログに出力します。post ステップは Cache saved をログに出力します。
  2. ローカルまたはデバッグ用のジョブで go build -x を実行してください。復元されたパッケージは再コンパイルされません。go test は、変更のないパッケージに対して (cached) を表示します。
  3. GOMODCACHE が温まっている場合、go mod download は 1 秒を大きく下回って完了するはずです。
  4. gh cache list --key setup-go --limit 20 でサイズと最終使用日時を確認できます。

よくある間違い

  1. モジュールグラフが go.sum に記録されている場合は、go.mod をハッシュします。 ほとんどのリポジトリでは両者は同時に変更されますが、go.sum はチェックサムの記録であるため、明示的なキャッシュではこれをキーにします。
  2. ベンダリングされたリポジトリのキャッシュ。 go mod vendor の結果をコミットしている場合、キャッシュ対象となるモジュールのダウンロードはありません。キャッシュするのは GOCACHE のみです。
  3. GOPATH/bin のキャッシュ。 go install でインストールしたツールは、ツールのバージョンをキーにする必要があります。
  4. 1 つのキーに複数の Go バージョン。 ビルドキャッシュは内部的に Go のバージョンごとに分けられますが、1 つのエントリにまとめると容量が無駄になります。マトリクスでは、キーにバージョンを含めてください。
  5. 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で実行できます。料金をご確認ください。

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

無料で試す