コンテンツへスキップ

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=ghatype=registrytype=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の比較モードで同じジョブをより大きなマシン上で実行し、実行ごとの時間と料金を比較できます。

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

無料で試す