metadata-action

关于

GitHub Action 用于从 Git 引用和 GitHub 事件中提取元数据。这个 action 特别适合与 Docker Build Push action 一起使用，用于标记和标签 Docker 镜像。

• 用法
  • 基础
  • 语义化版本
  • Bake 定义
• 自定义
  • inputs
  • outputs
  • 环境变量
• 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}}
    • {{date '<format>' tz='<timezone>'}}
  • 主版本号为零
  • 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@v4
      -
        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@v5
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

语义化版本

name: ci

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

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      -
        name: 检出
        uses: actions/checkout@v4
      -
        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@v5
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Bake 定义

这个 action 还支持 bake 定义文件，可与 Docker Bake action 一起使用。你只需声明一个名为 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: 检出
        uses: actions/checkout@v4
      -
        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@v4
        with:
          files: |
            ./docker-bake.hcl
            ${{ 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: 构建
        uses: docker/bake-action@v4
        with:
          files: |
            ./docker-bake.hcl
            ${{ steps.meta.outputs.bake-file-tags }}
            ${{ steps.meta.outputs.bake-file-labels }}
          targets: build

如果你正在使用Git上下文构建远程Bake定义,必须使用cwd://前缀指定仅包含元数据的bake文件位置:

      -
        name: 构建
        uses: docker/bake-action@v4
        with:
          source: "${{ github.server_url }}/${{ github.repository }}.git#${{ github.ref }}"
          files: |
            ./docker-bake.hcl
            cwd://${{ steps.meta.outputs.bake-file }}
          targets: build

自定义

输入

以下输入可用作step.with键:

List类型是换行分隔的字符串

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

输出

可用的输出如下:

另外,每个输出也会导出为环境变量:

• 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 action一起使用:

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

环境变量

context输入

context定义从何处获取上下文元数据:

# 默认
context: workflow
# 或
context: git

• workflow: 从工作流(GitHub上下文)获取上下文元数据。参见 https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
• git: 从工作流获取上下文元数据,并用当前Git上下文覆盖其中的一些内容,如ref和sha。

images输入

images定义用作tags基本名称的Docker镜像列表:

images: |
  name/foo
  ghcr.io/name/bar
  # 或
  name=name/foo
  name=ghcr.io/name/bar

扩展属性和默认值:

images: |
  name=,enable=true

• name=<string> 镜像基本名称
• enable=<true|false> 启用此条目(默认为true)

如果images为空,则会生成没有基本名称的标签。

flavor输入

flavor为tags定义全局行为:

flavor: |
  latest=auto
  prefix=
  suffix=

• latest=<auto|true|false>: 处理latest标签(默认为auto)
• prefix=<string>,onlatest=<true|false>: 每个生成的标签的全局前缀,可选择用于latest
• suffix=<string>,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=<number> 设置标签优先级顺序
• prefix=<string> 添加前缀
• suffix=<string> 添加后缀

如果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格式渲染日期。 默认tz为UTC。

扩展属性及默认值：

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

将用于推送标签事件， 需要一个有效的semver格式的Git标签，但你也可以通过value属性使用自定义值。

pattern属性支持Handlebars模板， 可使用以下表达式：

• raw ; 实际标签
• version ; {{major}}.{{minor}}.{{patch}}的简写（可包含预发布版本）
• major ; 主版本号
• minor ; 次版本号
• patch ; 修订版本号

*预发布版本（rc、beta、alpha）只会扩展{{version}}（或指定的{{raw}}）作为标签， 因为它们经常更新，并包含许多破坏性变更，作者认为这些版本还不适合公开使用。

扩展属性及默认值：

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

type=pep440

tags: |
  # 最小配置
  type=pep440,pattern={{version}}
  # 使用自定义值替代git标签
  type=pep440,pattern={{version}},value=1.0.0

将用于推送标签事件， 需要一个符合PEP 440的Git标签， 但你也可以通过value属性使用自定义值。

pattern属性支持Handlebars模板， 可使用以下表达式：

• raw ; 实际标签
• version ; 清理后的版本
• major ; 主版本号
• minor ; 次版本号
• patch ; 修订版本号

*开发版/预发布版/后发布版只会扩展{{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标签
  type=match,pattern=v(.*),group=1,value=v1.0.0

可以创建一个正则表达式来匹配Git标签的模式和捕获组。将用于推送标签事件， 但你也可以通过value属性使用自定义值。

扩展属性及默认值：

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

type=edge

tags: |
  # 最小配置
  type=edge
  # 定义默认分支
  type=edge,branch=main

edge 标签反映了 Git 仓库活动分支的最后一次提交。我通常更喜欢使用 edge 作为 Docker 标签，以获得更好的区分或通用模式。这也被官方镜像如 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 引用（或参考）：

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

扩展属性和默认值：

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 短提交（或指定的长提交）作为 Docker 标签，如 sha-ad132f5。

扩展属性和默认值：

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

注意事项

镜像名称和标签清理

为了符合规范， 镜像名称组件可以包含小写字母、数字和分隔符。分隔符定义为一个句点、一个或两个下划线， 或者一个或多个破折号。名称组件不能以分隔符开头或结尾。

标签名称必须是有效的 ASCII 字符序列，可以包含小写和大写字母、数字、下划线、句点和 破折号。标签名称不能以句点或破折号开头，最多可包含 128 个字符。

为了便于在工作流程中集成，此操作将自动：

• 将镜像名称转为小写
• 将标签中的无效字符序列替换为 -

最新标签

latest 标签通过 flavor 输入 处理。默认情况下（auto 模式） 会为以下情况生成：

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

要为特定分支名有条件地标记为最新，例如，如果您的默认分支名不是 master， 请使用带有布尔表达式的 type=raw：

tags: |
  # 为 master 分支设置最新标签
  type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'master') }}

您还可以使用 {{is_default_branch}} 全局表达式 为默认分支有条件地标记为最新：

tags: |
  # 为默认分支设置最新标签
  type=raw,value=latest,enable={{is_default_branch}}

priority 属性

priority=<int> 属性用于在最终列表中对标签进行排序。值越高，优先级越高。 列表中的第一个标签（优先级最高）将用作生成的 OCI 标签和 version 输出 的镜像版本。每个标签的 type 属性都有一个默认优先级：

全局表达式

以下 Handlebars 模板 表达式可用于 prefix、suffix、value 和 enable 属性：

tags: |
  # 动态设置分支名称作为前缀
  type=sha,prefix={{branch}}-
  # 动态设置分支名称和 sha 作为自定义标签
  type=raw,value=mytag-{{branch}}-{{sha}}

{{branch}}

返回触发工作流运行的分支名称。如果不是分支引用，则为空：

{{tag}}

返回触发工作流运行的标签名称。如果不是标签引用，则为空：

{{sha}}

返回触发工作流运行的短提交 SHA（例如，90dd603）。

{{base_ref}}

返回触发工作流运行的拉取请求的基本引用或目标分支。对于分支引用，将为空：

*当发生推送标签事件时，base_ref 在推送负载中可用，但并不总是返回预期的分支。 它也未在 GitHub 文档中记录。 我们保留它以保持向后兼容性，但不建议依赖它。 更多上下文请参见 #192。

{{is_default_branch}}

如果触发工作流运行的分支是默认分支，则返回 true，否则返回 false。

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

返回按照其 moment 格式 渲染的当前日期。 默认 tz 为 UTC。

主版本号为零

主版本号为零（0.y.z）用于初始开发阶段，可能随时发生变化。这意味着公共API不应被视为稳定。

在这种情况下，如果您使用带有{{major}}模式的type=semver，则不应生成Docker标签0。您可以按以下方式管理此行为：

# refs/tags/v0.1.2
tags: |
  # 输出 0.1.2
  type=semver,pattern={{version}}
  # 输出 0.1
  type=semver,pattern={{major}}.{{minor}}
  # 如果主版本号为零则禁用
  type=semver,pattern={{major}},enable=${{ !startsWith(github.ref, 'refs/tags/v0.') }}

JSON输出对象

json输出是一个由生成的标签和标签组成的JSON对象，您可以在工作流程中使用fromJSON函数进一步重用它们：

      -
        name: Docker meta
        uses: docker/metadata-action@v5
        id: meta
        with:
          images: name/app
      -
        name: Build and push
        uses: docker/build-push-action@v5
        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镜像格式规范不适合作为标签/注释，您可以像这样覆盖它们：

      -
        name: Docker meta
        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
            org.opencontainers.image.vendor=MyCompany

注释

自Buildx 0.12版本起，可以通过--annotation标志为镜像设置注释。

使用build-push-action时，您可以将annotations输入设置为metadata-action的annotations输出值：

      -
        name: Docker meta
        uses: docker/metadata-action@v5
        with:
          images: name/app
      -
        name: Build and push
        uses: docker/build-push-action@v5
        with:
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}

同样的操作也可以在bake-action中完成：

      -
        name: Docker meta
        uses: docker/metadata-action@v5
        with:
          images: name/app
      -
        name: Build
        uses: docker/bake-action@v4
        with:
          files: |
            ./docker-bake.hcl
            ${{ steps.meta.outputs.bake-file-tags }}
            ${{ steps.meta.outputs.bake-file-annotations }}
          targets: build

请注意，注释可以附加到清单中的多个不同级别。默认情况下，生成的注释将附加到镜像清单，但不同的注册表可能期望注释出现在不同的位置；一种常见做法是在镜像索引（如果存在）中读取注释，这通常用于多架构构建以索引特定平台的镜像。如果您想为注释指定级别，可以使用DOCKER_METADATA_ANNOTATIONS_LEVELS环境变量，用逗号分隔列表指定应附加注释的所有级别（默认为manifest）。以下配置演示了将注释同时附加到镜像清单和镜像索引的能力，尽管您的注册表可能只需要在索引级别添加注释。（也就是说，单独使用index可能就足够了。）请查阅您的注册表文档。

      -
        name: Docker meta
        uses: docker/metadata-action@v5
        with:
          images: name/app
        env:
          DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
      -
        name: Build and push
        uses: docker/build-push-action@v5
        with:
          tags: ${{ steps.meta.outputs.tags }}
          annotations: ${{ steps.meta.outputs.annotations }}

更多关于注释的信息，请参阅BuildKit文档。

贡献

想要贡献？太棒了！您可以在CONTRIBUTING.md中找到有关为此项目贡献的信息。