https://github.com/docker/metadata-action/blob/v5/README.md

README.md

概要

Git リファレンスや GitHub イベントからメタデータを抽出する GitHub Action です。このアクションは、Docker Build Push と組み合わせて使用すると非常に有用です。 Docker イメージにタグ付けやラベル付けを行う際に活用できます。

---

• 使用方法
  • 基本操作
  • SemVer 対応
  • Bake 定義
• カスタマイズ方法
  • 入力パラメータ
  • 出力パラメータ
  • 環境変数
• context 入力パラメータ
• images 入力パラメータ
• flavor 入力パラメータ
• tags 入力パラメータ
  • type=schedule
  • type=semver
  • type=pep440
  • type=match
  • type=edge
  • type=ref
  • type=raw
  • type=sha
• 注意事項
  • イメージ名とタグのサニタイズ処理
  • 最新タグの扱い
  • priority 属性
  • グローバル式
    • {{branch}}
    • {{tag}}
    • {{sha}}
    • {{base_ref}}
    • {{is_default_branch}}
    • {{is_not_default_branch}}
    • {{date '<format>' tz='<timezone>'}}
    • {{commit_date '<format>' tz='<timezone>'}}
  • メジャーバージョン0の扱い
  • JSON出力オブジェクト
  • ラベルとアノテーションの上書き
  • アノテーション
• 貢献方法

使用方法

基本例

name: ci

on:
  workflow_dispatch:
  push:
    branches:
      - 'master'
    tags:
      - 'v*'
  pull_request:
    branches:
      - 'master'

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: リポジトリのチェックアウト
        uses: actions/checkout@v5
      -
        name: Dockerメタデータ取得
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: name/app
      -
        name: DockerHubへのログイン
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: ビルドとプッシュ
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

イベント	参照	Dockerタグ
pull_request	refs/pull/2/merge	pr-2
push	refs/heads/master	master
push	refs/heads/releases/v1	releases-v1
push tag	refs/tags/v1.2.3	v1.2.3, latest
push tag	refs/tags/v2.0.8-beta.67	v2.0.8-beta.67, latest
workflow_dispatch	refs/heads/master	master

Semver

name: ci

on:
  push:
    branches:
      - 'master'
    tags:
      - 'v*'
  pull_request:
    branches:
      - 'master'

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: チェックアウト
        uses: actions/checkout@v5
      -
        name: Dockerメタ情報
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: |
            name/app
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
      -
        name: DockerHubにログイン
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: ビルドとプッシュ
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

イベント	参照	Dockerタグ
pull_request	refs/pull/2/merge	pr-2
push	refs/heads/master	master
push	refs/heads/releases/v1	releases-v1
push tag	refs/tags/v1.2.3	1.2.3, 1.2, latest
push tag	refs/tags/v2.0.8-beta.67	2.0.8-beta.67

Bake定義の使用方法

このアクションでは、Docker Bakeアクション と併用可能な Bake定義ファイルもサポートしています。空のターゲット docker-metadata-action を宣言し、このターゲットを継承するだけで使用できます。

// docker-bake.hcl
target "docker-metadata-action" {}

target "build" {
  inherits = ["docker-metadata-action"]
  context = "./"
  dockerfile = "Dockerfile"
  platforms = [
    "linux/amd64",
    "linux/arm/v6",
    "linux/arm/v7",
    "linux/arm64",
    "linux/386"
  ]
}

name: ci

on:
  push:
    branches:
      - 'master'
    tags:
      - 'v*'

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: Dockerメタデータ処理
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: |
            name/app
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=sha
      -
        name: ビルド実行
        uses: docker/bake-action@v6
        with:
          files: |
            ./docker-bake.hcl
            cwd://${{ steps.meta.outputs.bake-file }}
          targets: build

${{ steps.meta.outputs.bake-file }} ファイルの内容です。タグ情報と ラベル情報を組み合わせた結果、refs/tags/v1.2.3 参照を使用した場合の出力例は以下の通りです:

{
  "target": {
    "docker-metadata-action": {
      "tags": [
        "name/app:1.2.3",
        "name/app:1.2",
        "name/app:sha-90dd603",
        "name/app:latest"
      ],
      "labels": {
        "org.opencontainers.image.title": "Hello-World",
        "org.opencontainers.image.description": "これはあなたの最初のリポジトリです！",
        "org.opencontainers.image.url": "https://github.com/octocat/Hello-World",
        "org.opencontainers.image.source": "https://github.com/octocat/Hello-World",
        "org.opencontainers.image.version": "1.2.3",
        "org.opencontainers.image.created": "2020-01-10T00:30:00.000Z",
        "org.opencontainers.image.revision": "860c1904a1ce19322e91ac35af1ab07466440c37",
        "org.opencontainers.image.licenses": "MIT"
      },
      "args": {
        "DOCKER_META_IMAGES": "name/app",
        "DOCKER_META_VERSION": "1.2.3"
      }
    }
  }
}

タグ情報のみ、またはラベル情報のみを使用したい場合は、bake-file-tags と bake-file-labels の出力結果を利用することもできます。以下はその使用例です: 前の例と同様の内容です:

      -
        name: Build
        uses: docker/bake-action@v6
        with:
          files: |
            ./docker-bake.hcl
            cwd://${{ steps.meta.outputs.bake-file-tags }}
            cwd://${{ steps.meta.outputs.bake-file-labels }}
          targets: build

カスタマイズ方法

入力パラメータ

以下の入力パラメータは step.with キーとして使用できます:

Note

List 型は改行で区切られた文字列として扱われます

labels: |
  org.opencontainers.image.title=MyCustomTitle
  org.opencontainers.image.description=Another description
  org.opencontainers.image.vendor=MyCompany

パラメータ名	型	説明
context	文字列	コンテキストデータを取得する場所。使用可能なオプション: workflow（デフォルト）、git
images	リスト	タグのベース名として使用するDockerイメージのリスト
tags	リスト	タグをキー値ペアの属性として指定するリスト
flavor	リスト	フレーバーを適用するためのリスト
labels	リスト	カスタムラベルのリスト
annotations	リスト	カスタムアノテーションのリスト
sep-tags	文字列	タグ出力時に使用する区切り文字（デフォルトは \n）
sep-labels	文字列	ラベル出力時に使用する区切り文字（デフォルトは \n）
sep-annotations	文字列	アノテーション出力時に使用する区切り文字（デフォルトは \n）
bake-target	文字列	ベイク対象の名前（デフォルトは docker-metadata-action）

出力項目

以下の出力項目が利用可能です：

名称	型	説明
version	文字列	Dockerイメージのバージョン
labels	文字列	Dockerラベル
bake-file-tags	ファイル	ベイクファイル定義 のパスにタグを追加したファイル
bake-file-labels	ファイル	ベイクファイル定義 のパスにラベルを追加したファイル
bake-file-annotations	ファイル	ベイクファイル定義 のパスにアノテーションを追加したファイル

また、DOCKER_METADATA_SET_OUTPUT_ENV が true に設定されている場合、各出力結果は環境変数としてもエクスポートされます：

• DOCKER_METADATA_OUTPUT_VERSION
• DOCKER_METADATA_OUTPUT_TAGS
• DOCKER_METADATA_OUTPUT_LABELS
• DOCKER_METADATA_OUTPUT_ANNOTATIONS
• DOCKER_METADATA_OUTPUT_JSON
• DOCKER_METADATA_OUTPUT_BAKE_FILE_TAGS
• DOCKER_METADATA_OUTPUT_BAKE_FILE_LABELS
• DOCKER_METADATA_OUTPUT_BAKE_FILE_ANNOTATIONS

これにより、当社のDocker Build Pushアクション で利用することが可能です：

- uses: docker/build-push-action@v6
  with:
    build-args: |
      DOCKER_METADATA_OUTPUT_JSON

環境変数

変数名	型	説明
DOCKER_METADATA_PR_HEAD_SHA	ブール	プルリクエストイベントでワークフローをトリガーしたコミットSHAではなく、関連するヘッドSHAを設定する場合にtrueに設定します
DOCKER_METADATA_SHORT_SHA_LENGTH	数値	短いコミットSHAの長さを指定し、一意性を確保します。デフォルト値は7ですが、リポジトリが大きい場合は値を増やすことが可能です
DOCKER_METADATA_ANNOTATIONS_LEVELS	文字列	注釈出力に設定する注釈レベルをカンマ区切りで指定します（デフォルトはmanifest）
DOCKER_METADATA_SET_OUTPUT_ENV	ブール	trueに設定すると、各出力を環境変数として設定します（デフォルトはtrue）

context 入力

contextはコンテキストメタデータを取得する場所を指定します:

# デフォルト設定
context: workflow
# または
context: git

• workflow: ワークフローからコンテキストメタデータを取得します（GitHubコンテキスト）。詳細は https://docs.github.com/en/actions/learn-github-actions/contexts#github-context を参照してください
• git: ワークフローからコンテキストメタデータを取得し、さらにrefやshaなどの一部のメタデータを現在のGitコンテキストで上書きします

images 入力

imagesはtagsのベース名として使用するDockerイメージのリストを指定します:

images: |
  name/foo
  ghcr.io/name/bar
  # または
  name=name/foo
  name=ghcr.io/name/bar

拡張属性とデフォルト値:

images: |
  name=,enable=true

• name=<文字列>: イメージのベース名を指定します
• enable=<true|false>: このエントリを有効にします（デフォルトはtrue）

imagesが空の場合、ベース名なしでタグが生成されます。

flavor 入力

flavorはtagsに対するグローバルな動作設定を定義します:

flavor: |
  latest=auto
  prefix=
  suffix=

• latest=<auto|true|false>: latestタグの処理方法を指定します（デフォルトはauto）
• prefix=<文字列>,onlatest=<true|false>: 生成される各タグに適用されるグローバルプレフィックスと、オプションでlatestタグにも適用するかどうかを指定します
• suffix=<文字列>,onlatest=<true|false>: 生成される各タグに適用されるグローバルサフィックスと、オプションでlatestタグにも適用するかどうかを指定します

tags 入力

tagsはこのアクションの中核となる入力項目で、この項目に関連するすべての情報が出力メタデータに反映されます。この入力形式はCSV形式のキー値ペアリストとなっており、GitHub Actionsに本来備わっている制約（入力フィールドでは文字列形式しか扱えない）を回避するためのものです。以下に使用例を示します:

tags: |
  type=schedule
  type=semver,pattern={{version}}
  type=semver,pattern={{major}}.{{minor}}
  type=semver,pattern={{major}}
  type=ref,event=branch
  type=ref,event=pr
  type=sha

各エントリはtypeによって定義され、以下の種類があります:

• type=schedule
• type=semver
• type=pep440
• type=match
• type=edge
• type=ref
• type=raw
• type=sha

また、グローバル属性として以下の設定が可能です:

• enable=<true|false>: このエントリを有効にします（デフォルトはtrue）
• priority=<数値>: タグの優先度の順序を設定します
• prefix=<文字列>: プレフィックスを追加します
• suffix=<文字列>: サフィックスを追加します

tags入力が空の場合のデフォルトエントリ:

tags: |
  type=schedule
  type=ref,event=branch
  type=ref,event=tag
  type=ref,event=pr

type=schedule

tags: |
  # 最小限の設定例
  type=schedule
  # デフォルト設定
  type=schedule,pattern=nightly
  # Handlebarsテンプレート使用
  type=schedule,pattern={{date 'YYYYMMDD'}}
  # タイムゾーン付きHandlebarsテンプレート
  type=schedule,pattern={{date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}

これはスケジュールイベントで使用されます。 patternはHandlebarsテンプレートをサポートするために特別に設計された属性で、以下の表現をサポートします:

• date 'format' tz='Timezone' ; moment.jsのフォーマットに従って日付をレンダリングします。 デフォルトのtzはUTCです。

パターン	出力結果
nightly	nightly
{{date 'YYYYMMDD'}}	20200110
{{date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}	20200110-093000

拡張属性とデフォルト値:

tags: |
  type=schedule,enable=true,priority=1000,prefix=,suffix=,pattern=nightly

type=semver

tags: |
  # 最小限の設定例
  type=semver,pattern={{version}}
  # gitタグの代わりにカスタム値を使用する場合
  type=semver,pattern={{version}},value=v1.0.0
  # カスタム値を使用し、その一部をマッチングする場合
  type=semver,pattern={{version}},value=p1/v1.0.0,match=v(\d.\d.\d)$

プッシュタグイベントで使用されます。 有効なsemver形式のGitタグが必要ですが、value属性を使用してカスタム値を指定することも可能です。

pattern属性はHandlebarsテンプレートをサポートしており、以下の表現が使用できます:

• raw ; 実際のタグ名
• version ; {{major}}.{{minor}}.{{patch}}の省略形（プレリリース版を含むことができます）
• major ; メジャーバージョン識別子
• minor ; マイナーバージョン識別子
• patch ; パッチバージョン識別子

Gitタグ	パターン	マッチング結果	出力結果
v1.2.3	{{raw}}		v1.2.3
v1.2.3	{{version}}		1.2.3
v1.2.3	{{major}}.{{minor}}		1.2
v1.2.3	v{{major}}		v1
v1.2.3	{{minor}}		2
v1.2.3	{{patch}}		3
p1/v1.2.3	{{version}}	v(\d.\d.\d)$	1.2.3
v2.0.8-beta.67	{{raw}}		v2.0.8-beta.67
v2.0.8-beta.67	{{version}}		2.0.8-beta.67
v2.0.8-beta.67	{{major}}		2.0.8-beta.67*
v2.0.8-beta.67	{{major}}.{{minor}}		2.0.8-beta.67*

Important

*プレリリース版（rc、beta、alpha）は頻繁に更新され、多くのバージョンが存在するため、 {{version}}（または指定されている場合は{{raw}}）のみをタグとして拡張します。 これらのバージョンには 著者の設計上、公開利用には適さない重大な変更が含まれている場合があります。

拡張属性とデフォルト値:

tags: |
  type=semver,enable=true,priority=900,prefix=,suffix=,pattern=,value=,match=

type=pep440

tags: |
  # 最小限の設定
  type=pep440,pattern={{version}}
  # gitタグではなくカスタム値を使用する場合
  type=pep440,pattern={{version}},value=1.0.0
  # カスタム値を使用し、その一部をマッチングする場合
  type=pep440,pattern={{version}},value=p1/v1.0.0,match=v(\d.\d.\d)$

プッシュタグイベントで使用され、 PEP 440に準拠したGitタグが必要ですが、 value属性を使用してカスタム値を指定することも可能です。

pattern属性はHandlebarsテンプレートをサポートしており、 以下の表現を使用できます:

• raw ; 実際のタグ名
• version ; クリーンなバージョン番号
• major ; メジャーバージョン識別子
• minor ; マイナーバージョン識別子
• patch ; パッチバージョン識別子

Gitタグ	パターン	マッチ結果	出力結果
1.2.3	{{raw}}		1.2.3
1.2.3	{{version}}		1.2.3
v1.2.3	{{version}}		1.2.3
1.2.3	{{major}}.{{minor}}		1.2
1.2.3	v{{major}}		v1
v1.2.3rc2	{{raw}}		v1.2.3rc2
1.2.3rc2	{{version}}		1.2.3rc2
p1/v1.2.3	{{version}}	v(\d.\d.\d)$	1.2.3
1.2.3rc2	{{major}}.{{minor}}		1.2.3rc2*
1.2.3post1	{{major}}.{{minor}}		1.2.3.post1*
1.2.3beta2	{{major}}.{{minor}}		1.2.3b2*
1.0dev4	{{major}}.{{minor}}		1.0.dev4*

Important

*dev/pre/postリリースの場合、タグは{{version}}（または{{raw}}が指定されている場合はその値）のみを拡張します。これらのリリースは頻繁に更新され、多くの互換性を損なう変更が含まれているため（著者の設計上、現時点では一般公開に適していません）、タグとしてのみ使用されます。

拡張属性とデフォルト値:

tags: |
  type=pep440,enable=true,priority=900,prefix=,suffix=,pattern=,value=

type=match

tags: |
  # 最小限の設定例
  type=match,pattern=\d.\d.\d
  # マッチグループを定義する場合
  type=match,pattern=v(.*),group=1

Gitタグとパターンを照合し、キャプチャグループを使用する正規表現を作成できます。プッシュタグイベントで使用されますが、value属性を通じてカスタム値を指定することも可能です。

Gitタグ	パターン	グループ	出力結果
v1.2.3	\d.\d.\d	0	1.2.3
v2.0.8-beta.67	v(.*)	1	2.0.8-beta.67
v2.0.8-beta.67	v(\d.\d)	1	2.0
20200110-RC2	\d+	0	20200110
p1/v1.2.3	p1/v(\d.\d.\d)	1	1.2.3

拡張属性とデフォルト値:

tags: |
  type=match,enable=true,priority=800,prefix=,suffix=,pattern=,group=0,value=

type=edge

tags: |
  # 最小限の設定例
  type=edge
  # デフォルトブランチを定義
  type=edge,branch=main

edge タグは、Gitリポジトリの現在アクティブなブランチの最終コミットを反映します。 私は通常、Dockerイメージのタグとして edge を使用することを推奨しています。これにより、 より明確な区別が可能になり、標準的なパターンとして定着しています。Alpine などの公式イメージでも同様の手法が採用されています。

拡張属性とデフォルト値:

tags: |
  type=edge,enable=true,priority=700,prefix=,suffix=,branch=$repo.default_branch

type=ref

tags: |
  # ブランチイベント用
  type=ref,event=branch
  # タグイベント用
  type=ref,event=tag
  # プルリクエストイベント用
  type=ref,event=pr

このタイプは以下のGit参照（ref）イベントを処理します:

• branch ; 例: refs/heads/master
• tag ; 例: refs/tags/v1.0.0
• pr ; 例: refs/pull/318/merge

イベント	Ref	出力結果
pull_request	refs/pull/2/merge	pr-2
push	refs/heads/master	master
push	refs/heads/my/branch	my-branch
push tag	refs/tags/v1.2.3	v1.2.3
push tag	refs/tags/v2.0.8-beta.67	v2.0.8-beta.67
workflow_dispatch	refs/heads/master	master

拡張属性とデフォルト値:

tags: |
  # ブランチイベント用
  type=ref,enable=true,priority=600,prefix=,suffix=,event=branch
  # タグイベント用
  type=ref,enable=true,priority=600,prefix=,suffix=,event=tag
  # プルリクエストイベント用
  type=ref,enable=true,priority=600,prefix=pr-,suffix=,event=pr

type=raw

tags: |
  type=raw,value=foo
  type=raw,value=bar
  # または
  type=raw,foo
  type=raw,bar
  # または
  foo
  bar

必要に応じてカスタムタグを出力します。

拡張属性とデフォルト値:

tags: |
  type=raw,enable=true,priority=200,prefix=,suffix=,value=

type=sha

tags: |
  # 最小限の形式（短いSHA）
  type=sha
  # 完全な長さのSHA
  type=sha,format=long

Gitの短いコミットハッシュ（または指定した場合は完全な長さ）を、 sha-860c190のようなDockerタグ形式で出力します。

デフォルトでは、短いコミットSHAの長さは7文字です。大規模なリポジトリの場合、 DOCKER_METADATA_SHORT_SHA_LENGTH環境変数を設定することで この長さを拡張できます:

      -
        name: Dockerメタデータ
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: |
            name/app
          tags: |
            type=sha
        env:
          DOCKER_METADATA_SHORT_SHA_LENGTH: 12

拡張属性とデフォルト値:

tags: |
  type=sha,enable=true,priority=100,prefix=sha-,suffix=,format=short

注意事項

イメージ名とタグのサニタイズ処理

仕様に準拠するため、 イメージ名の各コンポーネントには小文字の英字、数字、およびセパレータが使用できます。 セパレータとは、ピリオド、アンダースコア1文字または2文字、または1文字以上の ハイフンを指します。 イメージ名のコンポーネントは、セパレータで開始または終了することはできません。

タグ名は有効なASCII文字の連続である必要があり、小文字と大文字の英字、数字、アンダースコア、ピリオド、ハイフンを含めることができます。 ただし、タグ名はピリオドやハイフンで開始することはできず、最大128文字までです。

ワークフローへの統合を容易にするため、このアクションでは以下を自動的に実行します:

• イメージ名を小文字に変換します
• タグ名に含まれる無効な文字列を-に置換します

最新タグの扱い

latestタグはflavor入力パラメータを通じて処理されます。このタグは デフォルトで以下の場合に自動生成されます:

• type=ref,event=tag
• type=semver,pattern=...
• type=pep440,pattern=...
• type=match,pattern=...

特定のブランチ名に対して条件付きで最新タグを付ける場合（例えばデフォルトのブランチ名がmasterでない場合）、type=rawを使用し、ブール式で条件を指定します:

tags: |
  # masterブランチに対してlatestタグを設定
  type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'master') }}

また、{{is_default_branch}} グローバル式 を使用して、デフォルトブランチに対して条件付きでlatestタグを付けることもできます:

tags: |
  # デフォルトブランチに対してlatestタグを設定
  type=raw,value=latest,enable={{is_default_branch}}

priority 属性

priority=<int> 属性は、最終的なタグリストをソートするために使用します。値が大きいほど優先順位が高くなります。リストの先頭にあるタグ（優先順位が高い方）が、生成されるOCIラベルおよびversion出力のイメージバージョンとして採用されます。 各タグのtype属性にはデフォルトの優先順位が設定されています:

属性	デフォルト優先順位
schedule	1000
semver	900
pep440	900
match	800
edge	700
ref	600
raw	200
sha	100

グローバル式

tags入力のprefix、suffix、value、enable属性で使用する以下のHandlebarsテンプレート式は以下の通りです:

tags: |
  # ブランチ名をプレフィックスとして動的に設定
  type=sha,prefix={{branch}}-
  # カスタムタグとしてブランチ名とSHAを動的に設定
  type=raw,value=mytag-{{branch}}-{{sha}}

これらの式はlabelsやannotations入力にも適用可能です:

labels: |
  org.opencontainers.image.created={{commit_date 'YYYY-MM-DDTHH:mm:ss.SSS[Z]'}}

{{branch}}

ワークフロー実行のトリガーとなったブランチ名を返します。ブランチ参照でない場合、値は空になります:

イベント	参照	出力
pull_request	refs/pull/2/merge
push	refs/heads/master	master
push	refs/heads/my/branch	my-branch
push tag	refs/tags/v1.2.3

{{tag}}

ワークフロー実行のトリガーとなったタグ名を返します。タグ参照でない場合、値は空になります:

イベント	参照	出力
pull_request	refs/pull/2/merge
push	refs/heads/master
push	refs/heads/my/branch
push tag	refs/tags/v1.2.3	v1.2.3

{{sha}}

ワークフロー実行のトリガーとなったコミットの短いSHA値を返します (例: 90dd603)。

{{base_ref}}

ワークフロー実行のトリガーとなったプルリクエストのベース参照またはターゲットブランチを返します。ブランチ参照の場合は値が空になります:

イベント	参照	出力
pull_request	refs/pull/2/merge	master
push	refs/heads/master
push	refs/heads/my/branch
push tag*	refs/tags/v1.2.3	master

Important

*base_refはプッシュペイロードで利用可能ですが、必ずしも常に取得できるとは限りません。 特にプッシュタグイベントが発生した場合、期待するブランチが返されないことがあります。また、 GitHub公式ドキュメントにも記載がありません。 後方互換性のため保持していますが、この値に依存することは推奨されません。 詳細については#192を参照してください。

{{is_default_branch}}

ワークフロー実行のトリガーとなったブランチがデフォルトブランチである場合に true を返します ; それ以外の場合は false を返します。

{{is_not_default_branch}}

ワークフロー実行のトリガーとなったブランチがデフォルトブランチでない場合に true を返します; それ以外の場合は false を返します。

{{date '<format>' tz='<timezone>'}}

moment.jsのフォーマットに従って現在の日付を文字列形式で返します。 デフォルトのタイムゾーンはUTCです。

式	出力例
{{date 'YYYYMMDD'}}	20200110
{{date 'dddd, MMMM Do YYYY, h:mm:ss a'}}	金曜日, 2020年1月10日 15:25:50
{{date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}	20200110-093000

{{commit_date '<format>' tz='<timezone>'}}

現在のGitコミットがコミットされた日付を、moment.jsのフォーマットに従って文字列形式で返します。コミット日付が取得できない場合には現在の日付を返します。 デフォルトのタイムゾーンはUTCです。

式	出力例
{{commit_date 'YYYYMMDD'}}	20200110
{{commit_date 'dddd, MMMM Do YYYY, h:mm:ss a'}}	金曜日, 2020年1月10日 15:25:50
{{commit_date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}	20200110-093000

メジャーバージョン0の扱い

メジャーバージョン0（0.y.z）は初期開発段階用のバージョンであり、 いつでも変更される可能性があります。このため、公開APIは安定していると見なしてはいけません。

この場合、type=semver と {{major}} パターンを使用している場合、Dockerタグ0は生成されるべきではありません。この動作は以下のように制御できます：

# refs/tags/v0.1.2
tags: |
  # 0.1.2 として出力
  type=semver,pattern={{version}}
  # 0.1 として出力
  type=semver,pattern={{major}}.{{minor}}
  # メジャーバージョンが0の場合は無効化
  type=semver,pattern={{major}},enable=${{ !startsWith(github.ref, 'refs/tags/v0.') }}

JSON出力オブジェクト

json出力は、生成されたタグとラベルで構成されたJSONオブジェクトです。これにより、fromJSON関数 を使用してワークフロー内でこれらの値を再利用できます：

      -
        name: Dockerメタ情報
        uses: docker/metadata-action@v5
        id: meta
        with:
          images: name/app

      -
        name: ビルドとプッシュ
        uses: docker/build-push-action@v6
        with:
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          build-args: |
            BUILDTIME=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.created'] }}
            VERSION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.version'] }}
            REVISION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}

ラベルとアノテーションの上書き

OCI Image Format Specification で生成された値が ラベル/アノテーションとして適切でない場合、以下のように上書きすることができます:

      -
        name: Dockerメタデータ
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: name/app
          labels: |
            maintainer=CrazyMax
            org.opencontainers.image.title=MyCustomTitle
            org.opencontainers.image.description=Another description

アノテーション

Buildx 0.12以降では、--annotation フラグを使用してイメージにアノテーションを設定できるようになりました。

build-push-action を使用する場合、 metadata-action の annotations 出力値を annotations 入力として設定できます:

      -
        name: Dockerメタデータ
        uses: docker/metadata-action@v5
        with:
          images: name/app
      -
        name: ビルドとプッシュ

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

bake-action を使用する場合も同様の操作が可能です:

      -
        name: Dockerメタデータ
        uses: docker/metadata-action@v5
        with:
          images: name/app
      -
        name: ビルド
        uses: docker/bake-action@v6
        with:
          files: |
            ./docker-bake.hcl

            cwd://${{ steps.meta.outputs.bake-file-tags }}
            cwd://${{ steps.meta.outputs.bake-file-annotations }}
          targets: build

注釈はマニフェスト内のさまざまなレベルで付与可能であることにご注意ください。 デフォルトでは生成された注釈はイメージマニフェストに付加されますが、 異なるレジストリでは注釈を異なる位置に配置することを想定している場合があります。 一般的なプラクティスとして、画像インデックスが存在する場合はそこから注釈を読み込むことが推奨されます。 このインデックスはマルチアーキテクチャビルドでプラットフォーム固有のイメージを索引するためによく使用されます。 注釈を特定のレベルに指定したい場合は、 DOCKER_METADATA_ANNOTATIONS_LEVELS 環境変数 を使用し、 注釈を付加すべきすべてのレベルをカンマ区切りのリストで指定できます（デフォルト値は manifest です）。 以下の設定例では、イメージマニフェストと画像インデックスの両方に注釈を付与する機能を示していますが、 お使いのレジストリではインデックスレベルのみで注釈を必要としている場合もあります（つまり、index のみで十分な場合もあります）。 詳細については、ご利用のレジストリのドキュメントをご参照ください。

      -
        name: Dockerメタデータ
        uses: docker/metadata-action@v5
        with:
          images: name/app
        env:
          DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
      -
        name: ビルドとプッシュ
        uses: docker/build-push-action@v6
        with:
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}

注釈に関する詳細情報は、BuildKitドキュメント をご覧ください。

貢献について

プロジェクトへの貢献をご検討いただきありがとうございます。このプロジェクトへの貢献方法については、CONTRIBUTING.md をご覧ください。