GitHub ActionsでのDocker Buildxキャッシュ: gha、registry
最終更新
Docker ビルドを GitHub Actions でキャッシュするには、docker/setup-buildx-action と docker/build-push-action を使い、cache-from: type=gha と cache-to: type=gha,mode=max を指定します。これにより BuildKit のレイヤーキャッシュが GitHub Actions のキャッシュに保存されます。バックエンドは gha、registry、inline、local の 4 種類があります。このガイドでは、それぞれの設定方法、選び方、制限事項を説明します。
ビルドが遅く、原因がわからない場合は、まず CI で Docker ビルドが遅い を確認してください。概念については CI における Docker レイヤーキャッシュ を参照してください。
デフォルトの設定: type=gha
name: Docker
on:
push:
branches: [main]
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v7
with:
context: .
push: false
tags: app:ci
cache-from: type=gha
cache-to: type=gha,mode=max
Buildx のセットアップは必須です。Docker の公式ドキュメント (2026 年 10 月確認) によると、既定の docker ドライバーで gha バックエンドを使えるのは containerd イメージストアが有効な場合のみです。それ以外の場合は別のドライバーが必要になり、setup-buildx-action がそれを作成します。ワークフロー内では、キャッシュの URL とトークンが自動的に設定されます。
重要なパラメーター
Docker の gha バックエンドのドキュメントより:
| パラメーター | 既定値 | 意味 |
|---|---|---|
scope | buildkit | キャッシュオブジェクトの名前。イメージごとに 1 つ使用してください。 |
mode | min | min は最終イメージのレイヤーのみをエクスポートします。max はすべてのステージのすべてのレイヤーをエクスポートします。 |
ignore-error | false | キャッシュのエクスポートに失敗しても、ビルドを失敗させません。 |
マルチステージビルドでは mode=max を使用してください。 min では中間ステージ (依存関係のインストールやコンパイル処理など) がキャッシュに含まれず、そこが最も時間のかかる部分です。max ならそれらも保存されますが、キャッシュは大きくなります。
イメージごとに scope を設定してください。 既定の scope は共有されるため、1 つのリポジトリで 2 つのイメージをビルドすると、互いのキャッシュを上書きしてしまいます:
cache-from: type=gha,scope=web
cache-to: type=gha,scope=web,mode=max
マトリックスを使う場合は、マトリックスの値を scope に含めてください。例: scope=build-${{ matrix.platform }}。
ドキュメントには、URL または version 設定で選択できる新しいキャッシュサービス API (v2) も記載されています。GitHub 側の変更後にキャッシュエラーが出る場合は、Buildx と BuildKit のバージョンが最新かを確認してください。古いバージョンは旧 API を対象としているためです。
スロットリング
大量のキャッシュエクスポートは API のレート制限に達することがあります。ビルドアクションは github-token (既定値は secrets.GITHUB_TOKEN) を Buildx に渡し、スロットリングを避けやすくしています。この設定は残しておいてください。
type=gha の制限
- GitHub Actions のキャッシュに保存されるため、npm、pip など他のすべてのキャッシュと、リポジトリあたり 10 GB のクォータを共有します。
mode=maxの Docker キャッシュだけで数 GB を使うこともあります。 - 7 日間使用されなかったエントリは削除されます。リポジトリがクォータを超えた場合は、最も長く使われていないエントリから先に削除されます。詳しくは キャッシュの制限 を参照してください。
- PR はベースブランチのキャッシュを読み取り、自身の scope 付きエントリを書き込みます。ベースキャッシュを有効に保つため、
mainでもビルドしてください。 - セルフホストランナーは、構成によっては GitHub のキャッシュサービスにアクセスできない場合があります。依存する前に確認してください。レジストリキャッシュならこの問題を避けられます。
type=registry
キャッシュをコンテナレジストリにイメージとして保存します:
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v7
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:latest
cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max
キャッシュが大きい場合、ランナーが GitHub のキャッシュネットワーク上にない場合、またはローカルの開発者と CI でキャッシュを共有したい場合に使用します。Actions の 10 GB のクォータには含まれません (代わりにレジストリのストレージ規則が適用されます)。大きなキャッシュの push と pull はネットワーク時間がかかるため、レジストリはランナーの近くに置いてください。一部のレジストリはキャッシュマニフェストに対応していないので、利用するレジストリを確認してください。
type=inline
push するイメージにキャッシュのメタデータを埋め込み、cache-from でそのイメージ自体を利用できるようにします:
cache-from: type=registry,ref=ghcr.io/org/app:latest
cache-to: type=inline
最もシンプルな方法で、追加のタグは不要です。ただし mode=min のみサポートされるため、マルチステージビルドの中間ステージはキャッシュされません。単一ステージの Dockerfile には適していますが、マルチステージには向きません。
type=local
キャッシュをディレクトリに書き出し、actions/cache で保存します:
- uses: actions/cache@v6
with:
path: /tmp/.buildx-cache
key: buildx-${{ runner.os }}-${{ github.sha }}
restore-keys: |
buildx-${{ runner.os }}-
- uses: docker/build-push-action@v7
with:
context: .
cache-from: type=local,src=/tmp/.buildx-cache
cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
これは従来のパターンです。エクスポートのたびにディレクトリに追加されるため、自動では縮小しません。そのため、-new を古いディレクトリに移動するステップを追加する必要があります。ほとんどの場合は type=gha がこれに代わります。actions/cache のキーで完全に管理したいキャッシュがある場合にのみ local を使用してください。
どのバックエンドを選ぶか?
| 必要な要件 | 使用する場合 |
|---|---|
| シンプルで中規模までのイメージ | スコープ付きのtype=gha,mode=max |
| 大きなキャッシュが必要な場合、ノートPCと共有する場合、またはGitHubのキャッシュを使わない場合 | type=registry,mode=max |
| シングルステージのDockerfileで、設定を最小限にしたい場合 | type=inline |
actions/cacheによる完全な制御 | type=local |
キャッシュマウントと、新しいランナーで失われる理由
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txtを使うと、ビルドステップに永続的なディレクトリを割り当てられ、レイヤーを再実行しても pip がすべてを再ダウンロードしなくなります。ノートPCや長期間稼働するビルダーでは非常に便利な機能です。
GitHubホステッドランナーでは、デフォルトではこの機能の効果はありません。キャッシュマウントはビルダー上のBuildKitのローカル状態に保存され、cache-toがエクスポートするレイヤーキャッシュには含まれません。新しいランナーでは新しいBuildKitが起動するため、ジョブごとにマウントは空になります。type=ghaとtype=registryがエクスポートするのはマウントではなくレイヤーです。
キャッシュマウントに依存する場合の選択肢:
- ローカルでの最適化としてのみ扱い、CIではレイヤーキャッシュに頼ってください。
- マウントのディレクトリを自分で永続化します。
reproducible-containers/buildkit-cache-danceアクションなどのサードパーティ製ツールは、actions/cacheを通じてキャッシュマウントの内容を保存・復元できます。導入前にセキュリティ要件に照らして評価してください。 - 永続的なビルダーを使います。 専用のビルドサービスは実行間でBuildKitの状態を保持します。Depotは Dockerビルドでこの方式を採用しており、詳細はDepotとの比較をご覧ください。永続ディスクを備えたセルフホストランナーでも機能します。
キャッシュヒットを実現する
- 依存関係のレイヤーが先に来るようにDockerfileを並べ替えてください(Dockerビルドが遅い場合を参照)。
.dockerignoreは厳密に設定してください。--progress=plainまたはビルドサマリーを使い、CACHEDの行を確認してください。- ブランチが読み取るベースを用意するため、
mainでビルドしてください。
compiler.devでは、ジョブ間でDockerレイヤーキャッシュをマシン上に保持するため、通常のdocker buildでもエクスポートなしにレイヤーを再利用できます。runs-on: [self-hosted, Linux, compiler-ci]に切り替えてください。詳細は料金をご覧ください。
よくある質問
mode=maxとmode=minのどちらを使うべきですか?
マルチステージビルドにはmaxを使ってください。中間ステージもキャッシュされます。minはサイズが小さく、シングルステージのイメージには十分です。
2つのイメージがお互いのキャッシュを上書きするのはなぜですか?
両方がデフォルトのスコープbuildkitを共有しているためです。それぞれに固有のscopeを指定してください。
セルフホストランナーでtype=ghaを使えますか?
ランナーがGitHubのキャッシュサービスに到達できるかどうかによります。小さなビルドで試すか、レジストリキャッシュを使ってください。
ghaキャッシュは10 GBの上限に含まれますか?
はい。同じActionsキャッシュに保存されます。
setup-buildx-actionは必要ですか?
type=ghaとほとんどのバックエンドでは必要です。デフォルトのドライバーは、containerdイメージストアを使わない限りこれらをサポートしていません。
関連記事
- 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 で Gradle ビルドをキャッシュするgradle/actions/setup-gradle または actions/cache を使用して、GitHub Actions で Gradle の依存関係とビルドキャッシュをキャッシュします。キー、プルリクエストでの読み取り専用設定、クリーンアップ、確認方法を解説します。
- GitHub Actions で npm の依存関係をキャッシュするsetup-node または actions/cache を使用して、GitHub Actions で npm の依存関係をキャッシュします。動作する YAML、適切なキー、node_modules をキャッシュしない理由、キャッシュヒットの確認方法を解説します。