GitHub Actions で Docker Push する

概要

この記事では、GitHub Actions を使ってタグ push（v*）をトリガーに Docker イメージをビルドしてプライベートなコンテナレジストリ（registry.uniproject.jp）へプッシュするワークフローの設定例を解説します。実際のワークフローは以下のようになっていて、ポイントごとに詳しく説明します。

name: Docker Build and Push
on:
  push:
    tags:
      - "v*"

concurrency:
  group: docker-build-push
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Extract tag name
        run: tagname=${GITHUB_REF#refs/*/} && echo "TAG_NAME=${tagname#v}" >> $GITHUB_ENV

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: registry.uniproject.jp
          username: robot$github-publisher
          password: ${{ secrets.HARBOR_TOKEN }}

      - name: Add metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: registry.uniproject.jp/infra/unibot
          tags: |
            type=raw,value=latest
            type=semver,pattern={{version}}
            type=sha,prefix=,suffix=,format=short
      - name: Push Docker image
        uses: docker/build-push-action@v5
        with:
          file: ./Dockerfile
          push: true
          context: .
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=registry,ref=registry.uniproject.jp/infra/unibot:buildcache
          cache-to: type=registry,ref=registry.uniproject.jp/infra/unibot:buildcache,mode=max

各セクションの解説

• トリガー（on: push tags）
  • v* のタグが push されたときのみ動きます。リリースタグ（例: v1.2.3）を push したタイミングで自動でイメージを作る運用に向きます。
• concurrency
  • 同じグループのジョブが並列で走らないようにします。cancel-in-progress: true にしておくと新しいビルドで古いビルドをキャンセルしてくれるので、無駄なビルドを減らせます。
• actions/checkout@v4
  • リポジトリのファイルをチェックアウトします。Dockerfile がリポジトリルートにある想定です。
• docker/setup-buildx-action@v3
  • Buildx を使うことでマルチプラットフォームビルドやキャッシュが使いやすくなります。将来的に platforms: linux/amd64,linux/arm64 を追加するとマルチアーキに対応できます。
• タグ名の抽出
  • GITHUB_REF は refs/tags/v1.2.3 のような形式なので、シェルで v を取り除き TAG_NAME 環境変数に入れています。後段でバージョンラベルに使えます。
• レジストリへのログイン
  • docker/login-action を使って registry.uniproject.jp にログインします。ここでは username: robot$github-publisher と password: ${{ secrets.HARBOR_TOKEN }} を利用しています。HARBOR_TOKEN は GitHub リポジトリの Settings > Secrets and variables > Actions に登録して使ってください。
• docker/metadata-action@v5
  • ここでイメージ名やタグの組み立てを行っています。type=raw,value=latest で latest タグを付与し、type=semver,pattern={{version}} で semver に応じたタグ（1.2.3）を付与します。type=sha は短いコミット SHA を付ける設定です。
• docker/build-push-action@v5
  • file, context, tags, labels, cache-from, cache-to を指定してビルドとプッシュを行います。
  • cache-from / cache-to に registry の参照を使うことで、レジストリに保存したキャッシュを再利用できます。ビルド時間短縮に有効です。

注意点とおすすめ設定

• Secrets の準備
  • HARBOR_TOKEN のようなトークンは GitHub の Actions Secrets に登録してください。もし Harbor 側でアクセストークンを作る場合は、必要な権限（push, pull, read）を付与しておきます。
• ユーザー名の扱い
  • username: robot$github-publisher のような syntactic な名前は Harbor 側で事前に用意された robot アカウントを使う想定です。環境に合わせて書き換えてください。
• マルチアーキテクチャ対応
  • docker/build-push-action に platforms: linux/amd64,linux/arm64 を追加すると複数アーキ向けイメージを同時にビルドできます。Buildx のセットアップが必須です。
• キャッシュの運用
  • cache-to に mode=max を指定するとキャッシュを最大限に使いますが、キャッシュのサイズやレジストリのポリシーに注意してください。必要に応じて TTL を設定したり、専用の buildcache タグを管理するとよいです。

よくあるトラブルと対処法

• 認証エラー
  • unauthorized などのエラーが出る場合は、HARBOR_TOKEN が正しいか、トークンに push 権限があるかを確認してください。
• タグが生成されない（version が空）
  • GITHUB_REF の形式を確認してください。リリースフローでタグをプッシュしているか、または Actions 上で手動トリガーを使っている場合は入力に注意が必要です。
• キャッシュが効かない
  • cache-from の参照イメージが存在しないと効きません。最初のビルドではキャッシュがないため時間がかかる点は想定内です。レジストリに buildcache タグが成功時に残るか確認してください。

まとめ

このワークフローは、タグベースのリリースで自動的に Docker イメージをビルドしてプライベートレジストリにプッシュする構成例です。ポイントはタグの取り扱い、レジストリ認証、そしてビルドキャッシュの活用です。必要に応じて platforms を追加したり、ビルド引数を渡してカスタマイズしてください。

署名の方法とかがあまりわかってないので、わかる方いたら教えてください...