Buildxを使ったCIでのDockerレイヤーキャッシュ
最終更新日
CIランナーは毎回空の状態から始まるため、docker buildはレイヤーがない状態から始まり、すべてを再ビルドします。一般的なアプリのイメージでは、プッシュのたびにすべての依存関係を再インストールすることになります。レイヤーキャッシュを使うと、実行間でビルドキャッシュを保存することでこの問題を解決できます。このガイドでは、GitHub Actionsで重要な2つのバックエンドと、実際にキャッシュにヒットするDockerfileの書き方を紹介します。
まずDockerfileを修正する
キャッシュが役立つのは、ビルド間でレイヤーが同一に保たれる場合だけです。Dockerは、命令やコピーするファイルが変わると、そのレイヤーとそれ以降のすべてのレイヤーを無効にします。変更頻度の低いものを上に置いてください:
FROM node:22-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
FROM node:22-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
CMD ["node", "dist/server.js"]
npm ciのレイヤーは、ロックファイルが変わるまで再利用されます。インストールの前にCOPY . .を書いていると、ソースを編集するたびにすべてが再インストールされてしまいます。無関係なファイルでキャッシュが無効にならないよう、.git、node_modules、ビルド出力を指定した.dockerignoreを追加してください。
パッケージマネージャーには、BuildKitのキャッシュマウントを使うと、レイヤーを再ビルドしてもダウンロードキャッシュを保持できます:
RUN --mount=type=cache,target=/root/.npm npm ci
キャッシュマウントはレイヤーキャッシュではなくBuildKitのビルダー内に保存されるため、CIでは別途扱う必要があります(後述)。
バックエンド1: GitHub Actionsキャッシュ(type=gha)
最も簡単な設定では、Dockerのbuild-push-actionとGitHubのキャッシュサービスを使います:
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
with:
context: .
push: false
tags: myapp:ci
cache-from: type=gha
cache-to: type=gha,mode=max
mode=maxは、マルチステージビルドの中間ステージのレイヤーを含め、すべてのレイヤーをエクスポートします。デフォルトのmode=minは最終イメージのレイヤーだけをエクスポートするため、マルチステージのDockerfileには適していません。maxを使い、キャッシュが大きくなることを受け入れてください。
トレードオフは、GitHubのドキュメントに記載された上限に基づきます。キャッシュはリポジトリの10 GBのキャッシュストレージに含まれ、7日間使われなかったエントリは削除されます。また、他のActionsキャッシュと同様にブランチのスコープが適用されます。大きなイメージはすぐに容量を使い切り、他のキャッシュを削除してしまうことがあります。リポジトリで複数のイメージをビルドする場合は、イメージごとにscopeを指定してください:
cache-from: type=gha,scope=api
cache-to: type=gha,scope=api,mode=max
バックエンド2: レジストリキャッシュ(type=registry)
キャッシュをレジストリ(GHCR、ECR、Docker Hub)のイメージとして保存します。これはActionsキャッシュの容量には含まれず、より長く保持され、開発者のマシンや他のCIシステムとも共有できます:
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max
GHCRにプッシュするには、ジョブにpermissions: packages: writeが必要です。ECRの場合は、cache-toでimage-manifest=true,oci-mediatypes=trueを使ってください。ECRではキャッシュマニフェストにOCIメディアタイプが必要です。使用するレジストリのAWSおよびDockerのドキュメントを確認してください。対応状況はレジストリによって異なります。
どちらのバックエンドを選ぶか
| type=gha | type=registry | type=local と actions/cache | |
|---|---|---|---|
| セットアップ | 2行 | ログインとキャッシュ用タグ | 追加の移動ステップ |
| ストレージの上限 | リポジトリの10 GBキャッシュを共有 | レジストリの容量枠 | リポジトリの10 GBキャッシュを共有 |
| ノートPCとの共有 | なし | あり | なし |
| プルのコスト | キャッシュサービス | レジストリの送信量(多くは同一リージョン内) | キャッシュサービス |
多くのチームでは、まずtype=ghaから始め、イメージが大きい場合やGitHub以外でもビルドする場合にtype=registryへ移行することをおすすめします。
CIでのキャッシュマウント
RUN --mount=type=cacheのデータはcache-toではエクスポートされません。パッケージのダウンロードにキャッシュマウントを使っている場合は、reproducible-containers/buildkit-cache-danceのような補助ツールで保持できます。または、CIではマウントを使わず、インストールステップのレイヤーキャッシュに頼る方法もあります。多くのアプリでは後者の方がシンプルです。
動作を確認する
ビルドログでは、キャッシュされたステップにCACHEDと表示されます。インストールのレイヤーが毎回実行される場合は、次の原因を確認してください:
- インストールステップの前に
COPY . .がある。 - 実行ごとに変わるビルド引数やタイムスタンプがある(インストールの前の
ARG BUILD_DATEなど)。 .dockerignoreがなく、無関係なファイルでコンテキストのハッシュが変わる。- マルチステージビルドで
mode=minのキャッシュを使っている。 node:22-slimのようなベースイメージのタグが更新された。これは正しい動作ですが、それ以降のすべてのキャッシュが無効になります。キャッシュヒットを予測可能にしたい場合はダイジェストで固定し、Dependabotで更新してください。
イメージビルドのその他の高速化
- マルチアーキテクチャのイメージを配布しない限り、CIでは1つのプラットフォームだけをビルドしてください。QEMUによるエミュレーションのarm64ビルドはネイティブより何倍も遅くなります。両方が必要な場合は、そのジョブにネイティブのarm64ランナーを使ってください。
- プッシュとプルのサイズを減らすため、slimまたはdistrolessのベースイメージを使ってください。
- 後のジョブで
load: trueを使ってビルド済みイメージに対してテストを実行します。イメージを再ビルドする必要はありません。
よくある質問
GitHubには組み込みのDockerレイヤーキャッシュ機能はありますか?
GitHubがホストするランナーは、ジョブ間でDockerレイヤーを保持しません。上記のように、buildxを使ってキャッシュをエクスポートおよびインポートする必要があります。
buildxを使わずにレイヤーキャッシュを利用できますか?
従来のビルダーでは、リモートストアからキャッシュを同じ方法でインポートすることはできません。docker buildxまたはbuild-push-actionを通じてBuildKitを使用してください。
キャッシュがイメージより大きいのはなぜですか?
mode=maxは、すべてのステージと中間レイヤーを保存します。これは想定どおりの動作です。
レジストリキャッシュはフォークからのプルリクエストでも安全ですか?
フォークからのプルリクエストには、レジストリやシークレットへの書き込み権限は付与されません。そのような実行ではcache-fromのみを使用し、キャッシュへの書き込みはmainから行ってください。
次のステップ
パイプラインのその他の部分についてはGitHub Actionsを高速化する方法を、節約した時間を金額に換算するにはコスト計算ツールをご覧ください。イメージのビルドがCPUに依存している場合は、compiler.devの比較モードで同じジョブをより大きなマシン上で実行し、実行ごとの時間と料金を比較できます。
関連記事
- CIでDockerビルドが遅い?原因を特定して解決CIでDockerビルドが遅いですか?ビルドコンテキストのサイズ、.dockerignore、レイヤーの順序、キャッシュミス、BuildKitの設定を診断し、最も影響の大きい問題から修正しましょう。
- GitHub Actionsのキャッシュ: キー、上限、例actions/cache、setup-* のキャッシュ、restore-keys の仕組みを、コピーしてすぐ使える YAML、キャッシュのスコープとサイズ上限、ミスの原因とともに解説します。
- GitHub ActionsでのDockerのPullレート制限:対処法GitHub Actionsで「toomanyrequests: You have reached your pull rate limit」を解決する方法:Docker Hubの制限、docker/login-action、ミラー、GHCRの代替手段について解説します。
- DockerビルドのGitHub ActionsワークフローテンプレートBuildx、GitHubのキャッシュレイヤー、mainへのプッシュ時のGHCRへのプッシュを使ってDockerイメージをビルドする、最小限の権限で動作するGitHub Actionsワークフローのコピー&ペースト用サンプルです。