DockerイメージをCIで自動ビルドしてレジストリへプッシュする手順｜GitHub Actionsのタグ戦略とキャッシュ活用

この記事のポイント

・docker/build-push-actionでビルド～プッシュをワンステップで自動化できる
・ghcr.ioはGITHUB_TOKENだけで認証できるため外部シークレット不要
・cache-type=ghaを使うとGitHub Actionsのキャッシュでビルド時間を大幅短縮できる
・タグはgit sha・semverタグ・latestを組み合わせて再現性と利便性を両立する

# .github/workflows/docker-build.yml の基本形
name: Docker Build and Push

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - name: リポジトリをチェックアウトする
        uses: actions/checkout@v4

      - name: BuildKitを有効化する（必須）
        uses: docker/setup-buildx-action@v3

      - name: Dockerイメージをビルドする（プッシュなし）
        uses: docker/build-push-action@v6
        with:
          context: .
          push: false
          tags: my-app:latest

jobs:
  build:
    runs-on: ubuntu-24.04
    # GITHUB_TOKENにパッケージの書き込み権限を付与する（必須）
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

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

      - name: ghcr.ioにログインする
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          # GITHUB_TOKENはActionsが自動生成するシークレット
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: イメージをビルドしてghcr.ioへプッシュする
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest

      - name: Docker Hubにログインする
        uses: docker/login-action@v3
        with:
          # registry: を指定しない場合はDocker Hubがデフォルト
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: イメージをビルドしてDocker Hubへプッシュする
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ secrets.DOCKERHUB_USERNAME }}/my-app:latest

      - name: イメージメタデータ（タグ・ラベル）を生成する
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            # Gitタグが v1.2.3 のとき → 1.2.3, 1.2, 1, latest を自動生成
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=semver,pattern={{major}}
            # mainブランチへのプッシュ → edge タグを生成
            type=edge,branch=main

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          # metadata-actionが生成したタグを一括適用する
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

      - name: イメージメタデータを生成する（SHA付き）
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            # コミットSHA（先頭7文字）: sha-a1b2c3d
            type=sha,prefix=sha-,format=short
            # mainブランチのみ latest タグも付ける
            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest
          # ghaキャッシュを使う設定（最もシンプル）
          cache-from: type=gha
          cache-to: type=gha,mode=max

# GitHub Actionsのログ出力例
# => [internal] load build definition from Dockerfile                  0.1s
# => [internal] load .dockerignore                                     0.1s
# => [auth] library/ubuntu:pull token for registry-1.docker.io        0.0s
# => CACHED [1/4] FROM docker.io/library/ubuntu:24.04                 0.0s  ← キャッシュヒット
# => CACHED [2/4] RUN apt-get update && apt-get install -y ...        0.0s  ← キャッシュヒット
# => [3/4] COPY . /app                                                 0.2s
# => [4/4] RUN make build                                              8.3s
# => exporting to image                                                1.1s

      - uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest
          # キャッシュをghcr.ioに保存する
          cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:cache
          cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:cache,mode=max

# Dockerfile のマルチステージビルド例
# ビルドステージ: 開発ツールを含む重いイメージ
FROM golang:1.23 AS builder
WORKDIR /app
COPY go.mod go.sum ./
# 依存関係のダウンロードを別レイヤーにする（キャッシュが効きやすい）
RUN go mod download
COPY . .
RUN go build -o /app/server ./cmd/server

# 実行ステージ: ビルド成果物だけを含む軽量イメージ
FROM ubuntu:24.04 AS runner
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/server /usr/local/bin/server
CMD ["/usr/local/bin/server"]

name: Docker Build and Push

on:
  push:
    branches:
      - main
    tags:
      - 'v*.*.*'
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      packages: write

    steps:
      - name: リポジトリをチェックアウトする
        uses: actions/checkout@v4

      - name: BuildKitを有効化する
        uses: docker/setup-buildx-action@v3

      - name: ghcr.ioにログインする（PRでは不要なためスキップ）
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: イメージタグとラベルを生成する
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            # v1.2.3 タグ付きpush → semverタグを生成
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            # mainブランチpush → sha+latestタグを生成
            type=sha,prefix=sha-,format=short
            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
            # PRビルド → pr-42 形式のタグを生成（レジストリへはpushしない）
            type=ref,event=pr

      - name: ビルドしてプッシュする
        uses: docker/build-push-action@v6
        with:
          context: .
          # PRの場合はビルドのみ実施（プッシュしない）
          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

# ジョブに permissions を追加する
jobs:
  build:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      packages: write  # ← これが必須

# checkout の直後に必ず追加する
      - uses: docker/setup-buildx-action@v3

      - name: テスト起動してポートを確認する
        run: |
          docker run -d --name test-app -p 8080:8080 ghcr.io/${{ github.repository }}:latest
          sleep 3
          # ssコマンドでポートがListenされているか確認する
          ss -tlnp | grep 8080
          # アプリへのリクエストが通るかも確認する
          curl -f http://localhost:8080/healthz
          docker rm -f test-app