コンテンツへスキップ

DockerビルドのGitHub Actionsワークフローテンプレート

最終更新

これは動作する .github/workflows/ci.yml で、すべてのプルリクエストで Docker イメージをビルドし、main からは GitHub Container Registry (GHCR) にプッシュします。Buildx と GitHub Actions のレイヤーキャッシュを使用するため、変更のないレイヤーは再ビルドされません。

ワークフロー

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  IMAGE: ghcr.io/${{ github.repository }}

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3
        if: github.event_name != 'pull_request'
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE }}
          tags: |
            type=sha
            type=raw,value=latest,enable={{is_default_branch}}

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

分かりにくい部分の役割

  • 権限。 ワークフローのデフォルトは読み取り専用です。イメージをプッシュするのはこのジョブだけなので、ジョブに packages: write を追加しています。フォークからのプルリクエストには、とにかく読み取り専用のトークンが付与されるため、プッシュはできません。
  • setup-buildx-action は Buildx ビルダーを作成します。デフォルトの Docker ドライバーでは GitHub キャッシュをエクスポートできないため、cache-to: type=gha を使うにはこのステップが必要です。
  • プッシュする場合のみログイン。 プルリクエストではプッシュするものがないため、このステップはスキップされます。
  • docker/metadata-action は、タグと OCI ラベルを生成します。この例では、すべてのビルドにコミット SHA のタグを付け、デフォルトブランチでは latest を追加します。
  • push: の式。 プルリクエストではビルドのみを行い、Dockerfile が引き続き動作することを確認します。main へのプッシュではビルドとプッシュを行います。
  • cache-from と cache-to: type=gha,mode=max は GitHub Actions キャッシュの読み取りと書き込みを行います。mode=max はすべてのステージのすべてのレイヤーをキャッシュするため、マルチステージビルドで重要になりますが、より多くのキャッシュ容量を消費します。キャッシュの上限を参照してください。
  • Dockerfile の順序は、どの設定よりも重要です。 ソースをコピーする前にロックファイルをコピーし、依存関係をインストールしておけば、コードの変更で依存関係のレイヤーが無効になりません。キャッシュ技術の一覧は CI における Docker レイヤーキャッシュにあります。

バリエーション

マルチプラットフォームイメージ

Buildx の前に docker/setup-qemu-action@v3 を追加し、ビルドステップに platforms: linux/amd64,linux/arm64 を設定します。エミュレートされた arm64 ビルドは遅いため、速度が重要な場合はネイティブの ARM ランナーを使用してください。

プッシュ前のスキャン

プッシュの前にビルドしたイメージの脆弱性スキャンステップを追加し、重大度の高い検出結果があれば失敗させてください。

イメージ内でテストを実行

load: true、push: false を指定し、テストステージを含む最初のビルドステップを追加してから、その結果に対して docker run を実行します。同じキャッシュを通じてレイヤーを共有します。

Docker Hub または ECR

registry、ログインステップ、images を変更します。AWS の場合は、保存したキーの代わりに aws-actions/amazon-ecr-login@v2 と OIDC を使用してください。

デプロイジョブ

needs: build を指定した 2 つ目のジョブを追加し、プッシュされた SHA タグをデプロイします。

macOS

Docker は macOS ランナーでは利用できません。コンテナのビルドは Linux で行ってください。

より高速なマシンで実行する

Docker ビルドは CPU とディスクを多く消費し、レイヤーキャッシュはビルドの近くにある場合にのみ効果を発揮します。1 行を変更してください:

    runs-on: [self-hosted, Linux, compiler-ci]

このジョブは compiler.dev の新しい 8 vCPU マシンで実行されます。このマシンには Docker レイヤーキャッシュが保持され、元のランナーに自動的にフォールバックします。特にイメージのビルドでは、Depot などの専用ビルダーの方が高速な場合があります。選択肢の比較は高速な GitHub Actions ランナーをご覧ください。料金は 料金プランに掲載しています。

よくある質問

ビルドがキャッシュを使用しないのはなぜですか?

Buildx が設定されていること、cache-from と cache-to が一致していること、そして Dockerfile の初期のレイヤーが毎回変わっていないこと(例えば、リポジトリ全体を最初にコピーしていないこと)を確認してください。

GitHub キャッシュの容量は十分ですか?

リポジトリにはすべてのキャッシュで共有されるサイズ上限があり、古いエントリは削除されます。大きなイメージではこの上限をすぐに超える可能性があります。

フォークからのプルリクエストはイメージをプッシュしますか?

いいえ。プルリクエストでは push の式が false になり、フォークのトークンは読み取り専用です。

では、アーティファクトは何に使うのですか?

ジョブ間でビルド済みの tar ファイルを受け渡すには アーティファクトを使用してください。レイヤーキャッシュには使用しません。