GitHub Action to extract metadata from Git reference and GitHub events. This action is particularly useful if used with Docker Build Push action to tag and label Docker images.

• Usage
  • Basic
  • Semver
  • Bake definition
• Customizing
  • inputs
  • outputs
  • environment variables
• context input
• images input
• flavor input
• tags input
  • type=schedule
  • type=semver
  • type=pep440
  • type=match
  • type=edge
  • type=ref
  • type=raw
  • type=sha
• Notes
  • Image name and tag sanitization
  • Latest tag
  • priority attribute
  • Global expressions
    • {{branch}}
    • {{tag}}
    • {{sha}}
    • {{base_ref}}
    • {{is_default_branch}}
    • {{date '<format>' tz='<timezone>'}}
  • Major version zero
  • JSON output object
  • Overwrite labels
• Contributing

name: ci on: workflow_dispatch: push: branches: - 'master' tags: - 'v*' pull_request: branches: - 'master' jobs: docker: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Docker meta id: meta uses: docker/metadata-action@v4 with: images: name/app - name: Login to DockerHub if: github.event_name != 'pull_request' uses: docker/login-action@v2 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Build and push uses: docker/build-push-action@v4 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: Checkout uses: actions/checkout@v3 - name: Docker meta id: meta uses: docker/metadata-action@v4 with: images: |  name/app  tags: |  type=ref,event=branch  type=ref,event=pr  type=semver,pattern={{version}}  type=semver,pattern={{major}}.{{minor}}  - name: Login to DockerHub if: github.event_name != 'pull_request' uses: docker/login-action@v2 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - name: Build and push uses: docker/build-push-action@v4 with: context: . push: ${{ github.event_name != 'pull_request' }} tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }}

This action also handles a bake definition file that can be used with the Docker Bake action. You just have to declare an empty target named docker-metadata-action and inherit from it.

// 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: Checkout uses: actions/checkout@v3 - name: Docker meta id: meta uses: docker/metadata-action@v4 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: Build uses: docker/bake-action@v2 with: files: |  ./docker-bake.hcl  ${{ steps.meta.outputs.bake-file }}  targets: build

Content of ${{ steps.meta.outputs.bake-file }} file will look like this with refs/tags/v1.2.3 ref:

{ "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": "This your first repo!", "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" } } } }

Following inputs can be used as step.with keys

List type is a newline-delimited string

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

Following outputs are available

Alternatively, each output is also exported as an environment variable:

• DOCKER_METADATA_OUTPUT_VERSION
• DOCKER_METADATA_OUTPUT_TAGS
• DOCKER_METADATA_OUTPUT_LABELS
• DOCKER_METADATA_OUTPUT_JSON
• DOCKER_METADATA_OUTPUT_BAKE_FILE

So it can be used with our Docker Build Push action:

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

context defines where to get context metadata:

# default context: workflow # or context: git

• workflow: Get context metadata from the workflow (GitHub context). See https://docs.github.com/en/actions/learn-github-actions/contexts#github-context
• git: Get context metadata from the workflow and overrides some of them with current Git context, such as ref and sha.

images defines a list of Docker images to use as base name for tags:

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

Extended attributes and default values:

images: |  name=,enable=true

• name=<string> image base name
• enable=<true|false> enable this entry (default true)

flavor defines a global behavior for tags:

flavor: |  latest=auto  prefix=  suffix=

• latest=<auto|true|false>: Handle latest tag (default auto)
• prefix=<string>,onlatest=<true|false>: A global prefix for each generated tag and optionally for latest
• suffix=<string>,onlatest=<true|false>: A global suffix for each generated tag and optionally for latest

tags is the core input of this action as everything related to it will reflect the output metadata. This one is in the form of a key-value pair list in CSV format to remove limitations intrinsically linked to GitHub Actions (only string format is handled in the input fields). Here is an example:

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

Each entry is defined by a type, which are:

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

And global attributes:

• enable=<true|false> enable this entry (default true)
• priority=<number> set tag priority order
• prefix=<string> add prefix
• suffix=<string> add suffix

Default entries if tags input is empty:

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

tags: |  # minimal  type=schedule  # default  type=schedule,pattern=nightly  # handlebars  type=schedule,pattern={{date 'YYYYMMDD'}}  # handlebars with timezone  type=schedule,pattern={{date 'YYYYMMDD-hhmmss' tz='Asia/Tokyo'}}

Will be used on schedule event.

pattern is a specially crafted attribute to support Handlebars' template with the following expressions:

• date 'format' tz='Timezone' ; render date by its moment format. Default tz is UTC.

Extended attributes and default values:

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

tags: |  # minimal  type=semver,pattern={{version}}  # use custom value instead of git tag  type=semver,pattern={{version}},value=v1.0.0

Will be used on a push tag event and requires a valid semver Git tag, but you can also use a custom value through value attribute.

pattern attribute supports Handlebars template with the following expressions:

• raw ; the actual tag
• version ; shorthand for {{major}}.{{minor}}.{{patch}} (can include pre-release)
• major ; major version identifier
• minor ; minor version identifier
• patch ; patch version identifier

*Pre-release (rc, beta, alpha) will only extend {{version}} (or {{raw}} if specified) as tag because they are updated frequently, and contain many breaking changes that are (by the author's design) not yet fit for public consumption.

Extended attributes and default values:

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

tags: |  # minimal  type=pep440,pattern={{version}}  # use custom value instead of git tag  type=pep440,pattern={{version}},value=1.0.0

Will be used on a push tag event and requires a Git tag that conforms to PEP 440, but you can also use a custom value through value attribute.

pattern attribute supports Handlebars template with the following expressions:

• raw ; the actual tag
• version ; cleaned version
• major ; major version identifier
• minor ; minor version identifier
• patch ; patch version identifier

*dev/pre/post release will only extend {{version}} (or {{raw}} if specified) as tag because they are updated frequently, and contain many breaking changes that are (by the author's design) not yet fit for public consumption.

Extended attributes and default values:

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

tags: |  # minimal  type=match,pattern=\d.\d.\d  # define match group  type=match,pattern=v(.*),group=1  # use custom value instead of git tag  type=match,pattern=v(.*),group=1,value=v1.0.0

Can create a regular expression for matching Git tag with a pattern and capturing group. Will be used on a push tag event but, you can also use a custom value through value attribute.

Extended attributes and default values:

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

tags: |  # minimal  type=edge  # define default branch  type=edge,branch=main

An edge tag reflects the last commit of the active branch on your Git repository. I usually prefer to use edge as a Docker tag for a better distinction or common pattern. This is also used by official images like Alpine.

Extended attributes and default values:

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

tags: |  # branch event  type=ref,event=branch  # tag event  type=ref,event=tag  # pull request event  type=ref,event=pr

This type handles Git ref (or reference) for the following events:

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

Extended attributes and default values:

tags: |  # branch event  type=ref,enable=true,priority=600,prefix=,suffix=,event=branch  # tag event  type=ref,enable=true,priority=600,prefix=,suffix=,event=tag  # pull request event  type=ref,enable=true,priority=600,prefix=pr-,suffix=,event=pr

tags: |  type=raw,value=foo  type=raw,value=bar  # or  type=raw,foo  type=raw,bar  # or  foo  bar

Output custom tags according to your needs.

Extended attributes and default values:

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

tags: |  # minimal (short sha)  type=sha  # full length sha  type=sha,format=long

Output Git short commit (or long if specified) as Docker tag like sha-ad132f5.

Extended attributes and default values:

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

In order to comply with the specification, the image name components may contain lowercase letters, digits and separators. A separator is defined as a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator.

A tag name must be a valid ASCII chars sequences and may contain lowercase and uppercase letters, digits, underscores, periods and dashes. A tag name may not start with a period or a dash and may contain a maximum of 128 characters.

To ease the integration in your workflow, this action will automatically:

• Lowercase the image name
• Replace invalid chars sequences with - for tags

latest tag is handled through the flavor input. It will be generated by default (auto mode) for:

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

For conditionally tagging with latest for a specific branch name, e.g. if your default branch name is not master, use type=raw with a boolean expression:

tags: |  # set latest tag for master branch  type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'master') }}

You can also use the {{is_default_branch}} global expression to conditionally tag with latest for the default branch:

tags: |  # set latest tag for default branch  type=raw,value=latest,enable={{is_default_branch}}

priority=<int> attribute is used to sort tags in the final list. The higher the value, the higher the priority. The first tag in the list (higher priority) will be used as the image version for generated OCI label and version output. Each tags type attribute has a default priority:

The following Handlebars' template expressions for prefix, suffix, value and enable attributes are available:

tags: |  # dynamically set the branch name as a prefix  type=sha,prefix={{branch}}-  # dynamically set the branch name and sha as a custom tag  type=raw,value=mytag-{{branch}}-{{sha}}

Returns the branch name that triggered the workflow run. Will be empty if not a branch reference:

Returns the tag name that triggered the workflow run. Will be empty if not a tag reference:

Returns the short commit SHA that triggered the workflow run (e.g., 90dd603).

Returns the base ref or target branch of the pull request that triggered the workflow run. Will be empty for a branch reference:

*base_ref is available in the push payload but doesn't always seem to return the expected branch when the push tag event occurs. It's also not documented in GitHub docs. We keep it for backward compatibility, but it's not recommended relying on it. More context in #192.

Returns true if the branch that triggered the workflow run is the default one, otherwise false.

Returns the current date rendered by its moment format. Default tz is UTC.

Major version zero (0.y.z) is for initial development and may change at any time. This means the public API should not be considered stable.

In this case, Docker tag 0 should not be generated if you're using type=semver with {{major}} pattern. You can manage this behavior like this:

# refs/tags/v0.1.2 tags: |  # output 0.1.2  type=semver,pattern={{version}}  # output 0.1  type=semver,pattern={{major}}.{{minor}}  # disabled if major zero  type=semver,pattern={{major}},enable=${{ !startsWith(github.ref, 'refs/tags/v0.') }}

The json output is a JSON object composed of the generated tags and labels so that you can reuse them further in your workflow using the fromJSON function:

 - name: Docker meta uses: docker/metadata-action@v4 id: meta with: images: name/app - name: Build and push uses: docker/build-push-action@v4 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'] }}

If some OCI Image Format Specification labels generated are not suitable, you can overwrite them like this:

 - name: Docker meta id: meta uses: docker/metadata-action@v4 with: images: name/app labels: |  maintainer=CrazyMax  org.opencontainers.image.title=MyCustomTitle  org.opencontainers.image.description=Another description  org.opencontainers.image.vendor=MyCompany

Want to contribute? Awesome! You can find information about contributing to this project in the CONTRIBUTING.md