GitHub Actions でビルドする - GitHub Actions

GitHub Actions はリポジトリのイベントに応じてワークフローを実行する CI/CD サービス。`docker/build-push-action` を組み合わせれば、数十行の YAML でビルドとプッシュまで自動化できる。

概念図

構文

bash

.github/workflows/build.yml

実例

main への push で GHCR にイメージを作って push する最小構成。

bash

name: build-image
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - 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 }}:latest

主要アクションの役割

アクション	役割
`actions/checkout`	リポジトリをワーカーにチェックアウトする
`docker/setup-qemu-action`	QEMU をインストールしてクロスアーキテクチャビルドを可能にする
`docker/setup-buildx-action`	Buildx（BuildKit ベース）ビルダーを起動する
`docker/login-action`	レジストリ（GHCR / Docker Hub / ECR / GAR 等）にログイン
`docker/metadata-action`	ブランチ名・タグ・日時から動的にタグを組み立てる
`docker/build-push-action`	実際にビルドしてレジストリにプッシュする本体

多くの workflow は上 3 つ（checkout / buildx / login）を前段に置き、build-push-action を本体として使う構成になります。

認証と権限（permissions）

GHCR に push する場合は、ワークフローに permissions: packages: write を付ける必要があります。

また docker/login-action の password には secrets.GITHUB_TOKEN を渡すのが定石で、個人の PAT を発行する必要はありません。

外部レジストリの場合は、短命クレデンシャルを使うのが望ましいです。

AWS ECR なら aws-actions/configure-aws-credentials + OIDC、Google Artifact Registry なら Workload Identity Federation が最近の標準です。

長期アクセスキーを secrets に入れっぱなしにするのは避けます。

トリガーとタグ戦略

典型的なトリガーは次の 3 種で、それぞれタグ付けの方針を変えると扱いやすくなります。

トリガー	目的	タグ例
`push: branches: [main]`	本番用の最新	`latest`, `sha-<short>`
`push: tags: ["v*"]`	リリース	`v1.2.3`, `1`, `1.2`
`pull_request`	プレビュー／検査	`pr-<number>`

docker/metadata-action を使うと、これらを 1 箇所にまとめて書けます。

- uses: docker/metadata-action@v5
  id: meta
  with:
    images: ghcr.io/${{ github.repository }}
    tags: |
      type=ref,event=branch
      type=ref,event=pr
      type=semver,pattern={{version}}
      type=sha,format=short

ハマりがちな初手

push: true を忘れる: ビルドは成功するのにレジストリに何も上がらない。CI のログで push 済みかを必ず確認する
permissions を省略: GHCR への push が 403 になる。ジョブかワークフロー先頭に permissions: packages: write を入れる
タグを全部 latest で上書き: ロールバックが効かない。イミュータブルな sha-<short> タグも必ず併用する
.dockerignore を書かない: リポジトリ全体が context に入り、ビルドが巨大化する。node_modules、.git、ローカル生成物を除外する

概念図

構文

実例

主要アクションの役割

認証と権限（permissions）

トリガーとタグ戦略

ハマりがちな初手

関連トピック