コンテンツへスキップ

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 バックエンドのドキュメントより:

パラメーター既定値意味
scopebuildkitキャッシュオブジェクトの名前。イメージごとに 1 つ使用してください。
modeminmin は最終イメージのレイヤーのみをエクスポートします。max はすべてのステージのすべてのレイヤーをエクスポートします。
ignore-errorfalseキャッシュのエクスポートに失敗しても、ビルドを失敗させません。

マルチステージビルドでは 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がエクスポートするのはマウントではなくレイヤーです。

キャッシュマウントに依存する場合の選択肢:

  1. ローカルでの最適化としてのみ扱い、CIではレイヤーキャッシュに頼ってください。
  2. マウントのディレクトリを自分で永続化します。 reproducible-containers/buildkit-cache-danceアクションなどのサードパーティ製ツールは、actions/cacheを通じてキャッシュマウントの内容を保存・復元できます。導入前にセキュリティ要件に照らして評価してください。
  3. 永続的なビルダーを使います。 専用のビルドサービスは実行間でBuildKitの状態を保持します。Depotは Dockerビルドでこの方式を採用しており、詳細はDepotとの比較をご覧ください。永続ディスクを備えたセルフホストランナーでも機能します。

キャッシュヒットを実現する

  1. 依存関係のレイヤーが先に来るようにDockerfileを並べ替えてください(Dockerビルドが遅い場合を参照)。
  2. .dockerignoreは厳密に設定してください。
  3. --progress=plainまたはビルドサマリーを使い、CACHEDの行を確認してください。
  4. ブランチが読み取るベースを用意するため、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イメージストアを使わない限りこれらをサポートしていません。

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

無料で試す