GitHub Actions を使ったイメージアノテーションの追加

アノテーション (annotation) は、OCI イメージコンポーネントに対して任意のメタデータを指定できるものです。たとえばマニフェスト、インデックス、内容説明などが利用されます。

GitHub Actions を用いてイメージのビルド時にアノテーションを追加するには、メタデータアクションを利用します。これによって自動的に OCI 互換のアノテーションが生成されます。メタデータアクション build-push-action、 bake-action のいずれにおいても、参照する annotations をアノテーションとして生成します。

name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

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

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          push: true

name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

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

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

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

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build
        uses: docker/bake-action@v5
        with:
          files: |
            ./docker-bake.hcl
            ${{ steps.meta.outputs.bake-file-tags }}
            ${{ steps.meta.outputs.bake-file-annotations }}            
          push: true

アノテーションレベルの設定

デフォルトでアノテーションは、イメージマニフェストに置かれます。アノテーションレベル (annotation level) を設定するには、metadata-action ステップ内において環境変数 DOCKER_METADATA_ANNOTATIONS_LEVELS を用います。指定したいアノテーションのレベルをカンマ区切りのリストとして指定します。たとえば DOCKER_METADATA_ANNOTATIONS_LEVELS に index を指定すると、そのアノテーションはイメージマニフェスト内ではなくイメージインデックス内に置かれます。

以下の例は、アノテーション生成をイメージインデックスとイメージマニフェストの両方に生成するものです。

name: ci

on:
  push:

env:
  IMAGE_NAME: user/app

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

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

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE_NAME }}
        env:
          DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}
          push: true

メモ
The build must produce the components that you want to annotate. For example, to annotate an image index, the build must produce an index. If the build produces only a manifest and you specify index or index-descriptor, the build fails.