{"id":13484950,"url":"https://github.com/docker/metadata-action","last_synced_at":"2025-05-13T16:07:00.080Z","repository":{"id":37897293,"uuid":"306769011","full_name":"docker/metadata-action","owner":"docker","description":"GitHub Action to extract metadata (tags, labels) from Git reference and GitHub events for Docker","archived":false,"fork":false,"pushed_at":"2025-04-22T12:37:08.000Z","size":27173,"stargazers_count":985,"open_issues_count":27,"forks_count":129,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-22T13:48:09.795Z","etag":null,"topics":["docker","github-actions","github-actions-docker","labels","metadata","tags"],"latest_commit_sha":null,"homepage":"https://github.com/marketplace/actions/docker-metadata-action","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-23T23:38:33.000Z","updated_at":"2025-04-22T12:37:13.000Z","dependencies_parsed_at":"2023-12-15T21:10:41.402Z","dependency_job_id":"bbadec91-c6ef-4eee-9128-57006a9176df","html_url":"https://github.com/docker/metadata-action","commit_stats":{"total_commits":370,"total_committers":16,"mean_commits":23.125,"dds":"0.30000000000000004","last_synced_commit":"0de3687b53cd804b63dd87819f7bda043569ce4a"},"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docker%2Fmetadata-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docker%2Fmetadata-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docker%2Fmetadata-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docker%2Fmetadata-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docker","download_url":"https://codeload.github.com/docker/metadata-action/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250513380,"owners_count":21443200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","github-actions","github-actions-docker","labels","metadata","tags"],"created_at":"2024-07-31T17:01:39.969Z","updated_at":"2025-04-23T20:45:59.748Z","avatar_url":"https://github.com/docker.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"[![GitHub release](https://img.shields.io/github/release/docker/metadata-action.svg?style=flat-square)](https://github.com/docker/metadata-action/releases/latest)\n[![GitHub marketplace](https://img.shields.io/badge/marketplace-docker--metadata--action-blue?logo=github\u0026style=flat-square)](https://github.com/marketplace/actions/docker-metadata-action)\n[![CI workflow](https://img.shields.io/github/actions/workflow/status/docker/metadata-action/ci.yml?branch=master\u0026label=ci\u0026logo=github\u0026style=flat-square)](https://github.com/docker/metadata-action/actions?workflow=ci)\n[![Test workflow](https://img.shields.io/github/actions/workflow/status/docker/metadata-action/test.yml?branch=master\u0026label=test\u0026logo=github\u0026style=flat-square)](https://github.com/docker/metadata-action/actions?workflow=test)\n[![Codecov](https://img.shields.io/codecov/c/github/docker/metadata-action?logo=codecov\u0026style=flat-square)](https://codecov.io/gh/docker/metadata-action)\n\n## About\n\nGitHub Action to extract metadata from Git reference and GitHub events. This action\nis particularly useful if used with [Docker Build Push](https://github.com/docker/build-push-action)\naction to tag and label Docker images.\n\n![Screenshot](.github/metadata-action.png)\n\n___\n\n* [Usage](#usage)\n  * [Basic](#basic)\n  * [Semver](#semver)\n  * [Bake definition](#bake-definition)\n* [Customizing](#customizing)\n  * [inputs](#inputs)\n  * [outputs](#outputs)\n  * [environment variables](#environment-variables)\n* [`context` input](#context-input)\n* [`images` input](#images-input)\n* [`flavor` input](#flavor-input)\n* [`tags` input](#tags-input)\n  * [`type=schedule`](#typeschedule)\n  * [`type=semver`](#typesemver)\n  * [`type=pep440`](#typepep440)\n  * [`type=match`](#typematch)\n  * [`type=edge`](#typeedge)\n  * [`type=ref`](#typeref)\n  * [`type=raw`](#typeraw)\n  * [`type=sha`](#typesha)\n* [Notes](#notes)\n  * [Image name and tag sanitization](#image-name-and-tag-sanitization)\n  * [Latest tag](#latest-tag)\n  * [`priority` attribute](#priority-attribute)\n  * [Global expressions](#global-expressions)\n    * [`{{branch}}`](#branch)\n    * [`{{tag}}`](#tag)\n    * [`{{sha}}`](#sha)\n    * [`{{base_ref}}`](#base_ref)\n    * [`{{is_default_branch}}`](#is_default_branch)\n    * [`{{date '\u003cformat\u003e' tz='\u003ctimezone\u003e'}}`](#date-format-tztimezone)\n    * [`{{commit_date '\u003cformat\u003e' tz='\u003ctimezone\u003e'}}`](#commit_date-format-tztimezone)\n  * [Major version zero](#major-version-zero)\n  * [JSON output object](#json-output-object)\n  * [Overwrite labels and annotations](#overwrite-labels-and-annotations)\n  * [Annotations](#annotations)\n* [Contributing](#contributing)\n\n## Usage\n\n### Basic\n\n```yaml\nname: ci\n\non:\n  workflow_dispatch:\n  push:\n    branches:\n      - 'master'\n    tags:\n      - 'v*'\n  pull_request:\n    branches:\n      - 'master'\n\njobs:\n  docker:\n    runs-on: ubuntu-latest\n    steps:\n      -\n        name: Checkout\n        uses: actions/checkout@v4\n      -\n        name: Docker meta\n        id: meta\n        uses: docker/metadata-action@v5\n        with:\n          images: name/app\n      -\n        name: Login to DockerHub\n        if: github.event_name != 'pull_request'\n        uses: docker/login-action@v3\n        with:\n          username: ${{ secrets.DOCKERHUB_USERNAME }}\n          password: ${{ secrets.DOCKERHUB_TOKEN }}\n      -\n        name: Build and push\n        uses: docker/build-push-action@v6\n        with:\n          context: .\n          push: ${{ github.event_name != 'pull_request' }}\n          tags: ${{ steps.meta.outputs.tags }}\n          labels: ${{ steps.meta.outputs.labels }}\n```\n\n| Event               | Ref                           | Docker Tags                |\n|---------------------|-------------------------------|----------------------------|\n| `pull_request`      | `refs/pull/2/merge`           | `pr-2`                     |\n| `push`              | `refs/heads/master`           | `master`                   |\n| `push`              | `refs/heads/releases/v1`      | `releases-v1`              |\n| `push tag`          | `refs/tags/v1.2.3`            | `v1.2.3`, `latest`         |\n| `push tag`          | `refs/tags/v2.0.8-beta.67`    | `v2.0.8-beta.67`, `latest` |\n| `workflow_dispatch` | `refs/heads/master`           | `master`                   |\n\n### Semver\n\n```yaml\nname: ci\n\non:\n  push:\n    branches:\n      - 'master'\n    tags:\n      - 'v*'\n  pull_request:\n    branches:\n      - 'master'\n\njobs:\n  docker:\n    runs-on: ubuntu-latest\n    steps:\n      -\n        name: Checkout\n        uses: actions/checkout@v4\n      -\n        name: Docker meta\n        id: meta\n        uses: docker/metadata-action@v5\n        with:\n          images: |\n            name/app\n          tags: |\n            type=ref,event=branch\n            type=ref,event=pr\n            type=semver,pattern={{version}}\n            type=semver,pattern={{major}}.{{minor}}\n      -\n        name: Login to DockerHub\n        if: github.event_name != 'pull_request'\n        uses: docker/login-action@v3\n        with:\n          username: ${{ secrets.DOCKERHUB_USERNAME }}\n          password: ${{ secrets.DOCKERHUB_TOKEN }}\n      -\n        name: Build and push\n        uses: docker/build-push-action@v6\n        with:\n          context: .\n          push: ${{ github.event_name != 'pull_request' }}\n          tags: ${{ steps.meta.outputs.tags }}\n          labels: ${{ steps.meta.outputs.labels }}\n```\n\n| Event           | Ref                           | Docker Tags                         |\n|-----------------|-------------------------------|-------------------------------------|\n| `pull_request`  | `refs/pull/2/merge`           | `pr-2`                              |\n| `push`          | `refs/heads/master`           | `master`                            |\n| `push`          | `refs/heads/releases/v1`      | `releases-v1`                       |\n| `push tag`      | `refs/tags/v1.2.3`            | `1.2.3`, `1.2`, `latest`            |\n| `push tag`      | `refs/tags/v2.0.8-beta.67`    | `2.0.8-beta.67`                     |\n\n### Bake definition\n\nThis action also handles a bake definition file that can be used with the\n[Docker Bake action](https://github.com/docker/bake-action). You just have to\ndeclare an empty target named `docker-metadata-action` and inherit from it.\n\n```hcl\n// docker-bake.hcl\ntarget \"docker-metadata-action\" {}\n\ntarget \"build\" {\n  inherits = [\"docker-metadata-action\"]\n  context = \"./\"\n  dockerfile = \"Dockerfile\"\n  platforms = [\n    \"linux/amd64\",\n    \"linux/arm/v6\",\n    \"linux/arm/v7\",\n    \"linux/arm64\",\n    \"linux/386\"\n  ]\n}\n```\n\n```yaml\nname: ci\n\non:\n  push:\n    branches:\n      - 'master'\n    tags:\n      - 'v*'\n\njobs:\n  docker:\n    runs-on: ubuntu-latest\n    steps:\n      -\n        name: Docker meta\n        id: meta\n        uses: docker/metadata-action@v5\n        with:\n          images: |\n            name/app\n          tags: |\n            type=ref,event=branch\n            type=ref,event=pr\n            type=semver,pattern={{version}}\n            type=semver,pattern={{major}}.{{minor}}\n            type=sha\n      -\n        name: Build\n        uses: docker/bake-action@v6\n        with:\n          files: |\n            ./docker-bake.hcl\n            cwd://${{ steps.meta.outputs.bake-file }}\n          targets: build\n```\n\nContent of `${{ steps.meta.outputs.bake-file }}` file, combining tags and\nlabels, will look like this with `refs/tags/v1.2.3` ref:\n\n```json\n{\n  \"target\": {\n    \"docker-metadata-action\": {\n      \"tags\": [\n        \"name/app:1.2.3\",\n        \"name/app:1.2\",\n        \"name/app:sha-90dd603\",\n        \"name/app:latest\"\n      ],\n      \"labels\": {\n        \"org.opencontainers.image.title\": \"Hello-World\",\n        \"org.opencontainers.image.description\": \"This your first repo!\",\n        \"org.opencontainers.image.url\": \"https://github.com/octocat/Hello-World\",\n        \"org.opencontainers.image.source\": \"https://github.com/octocat/Hello-World\",\n        \"org.opencontainers.image.version\": \"1.2.3\",\n        \"org.opencontainers.image.created\": \"2020-01-10T00:30:00.000Z\",\n        \"org.opencontainers.image.revision\": \"860c1904a1ce19322e91ac35af1ab07466440c37\",\n        \"org.opencontainers.image.licenses\": \"MIT\"\n      },\n      \"args\": {\n        \"DOCKER_META_IMAGES\": \"name/app\",\n        \"DOCKER_META_VERSION\": \"1.2.3\"\n      }\n    }\n  }\n}\n```\n\nYou can also use the `bake-file-tags` and `bake-file-labels` outputs if you\njust want to use tags and/or labels respectively. The following example is\nsimilar to the previous one:\n\n```yaml\n      -\n        name: Build\n        uses: docker/bake-action@v6\n        with:\n          files: |\n            ./docker-bake.hcl\n            cwd://${{ steps.meta.outputs.bake-file-tags }}\n            cwd://${{ steps.meta.outputs.bake-file-labels }}\n          targets: build\n```\n\n## Customizing\n\n### inputs\n\nThe following inputs can be used as `step.with` keys:\n\n\u003e `List` type is a newline-delimited string\n\u003e ```yaml\n\u003e labels: |\n\u003e   org.opencontainers.image.title=MyCustomTitle\n\u003e   org.opencontainers.image.description=Another description\n\u003e   org.opencontainers.image.vendor=MyCompany\n\u003e ```\n\n| Name              | Type   | Description                                                                  |\n|-------------------|--------|------------------------------------------------------------------------------|\n| `context`         | String | Where to get context data. Allowed options are: `workflow` (default), `git`. |\n| `images`          | List   | List of Docker images to use as base name for tags                           |\n| `tags`            | List   | List of [tags](#tags-input) as key-value pair attributes                     |\n| `flavor`          | List   | [Flavor](#flavor-input) to apply                                             |\n| `labels`          | List   | List of custom labels                                                        |\n| `annotations`     | List   | List of custom annotations                                                   |\n| `sep-tags`        | String | Separator to use for tags output (default `\\n`)                              |\n| `sep-labels`      | String | Separator to use for labels output (default `\\n`)                            |\n| `sep-annotations` | String | Separator to use for annotations output (default `\\n`)                       |\n| `bake-target`     | String | Bake target name (default `docker-metadata-action`)                          |\n\n### outputs\n\nThe following outputs are available:\n\n| Name                    | Type   | Description                                                                                                                                                     |\n|-------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `version`               | String | Docker image version                                                                                                                                            |\n| `tags`                  | String | Docker tags                                                                                                                                                     |\n| `labels`                | String | Docker labels                                                                                                                                                   |\n| `annotations`           | String | [Annotations](https://github.com/moby/buildkit/blob/master/docs/annotations.md)                                                                                 |\n| `json`                  | String | JSON output of tags and labels                                                                                                                                  |\n| `bake-file-tags`        | File   | [Bake file definition](https://docs.docker.com/build/bake/reference/) path with tags                                                                            |\n| `bake-file-labels`      | File   | [Bake file definition](https://docs.docker.com/build/bake/reference/) path with labels                                                                          |\n| `bake-file-annotations` | File   | [Bake file definition](https://docs.docker.com/build/bake/reference/) path with [annotations](https://github.com/moby/buildkit/blob/master/docs/annotations.md) |\n\nAlternatively, each output is also exported as an environment variable when `DOCKER_METADATA_SET_OUTPUT_ENV` is `true`:\n\n* `DOCKER_METADATA_OUTPUT_VERSION`\n* `DOCKER_METADATA_OUTPUT_TAGS`\n* `DOCKER_METADATA_OUTPUT_LABELS`\n* `DOCKER_METADATA_OUTPUT_ANNOTATIONS`\n* `DOCKER_METADATA_OUTPUT_JSON`\n* `DOCKER_METADATA_OUTPUT_BAKE_FILE_TAGS`\n* `DOCKER_METADATA_OUTPUT_BAKE_FILE_LABELS`\n* `DOCKER_METADATA_OUTPUT_BAKE_FILE_ANNOTATIONS`\n\nSo it can be used with our [Docker Build Push action](https://github.com/docker/build-push-action/):\n\n```yaml\n- uses: docker/build-push-action@v6\n  with:\n    build-args: |\n      DOCKER_METADATA_OUTPUT_JSON\n```\n\n### environment variables\n\n| Name                                 | Type   | Description                                                                                                                                  |\n|--------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------|\n| `DOCKER_METADATA_PR_HEAD_SHA`        | Bool   | If `true`, set associated head SHA instead of commit SHA that triggered the workflow on pull request event                                   |\n| `DOCKER_METADATA_SHORT_SHA_LENGTH`   | Number | Specifies the length of the [short commit SHA](#typesha) to ensure uniqueness. Default is `7`, but can be increased for larger repositories. |\n| `DOCKER_METADATA_ANNOTATIONS_LEVELS` | String | Comma separated list of annotations levels to set for annotations output separated (default `manifest`)                                      |\n| `DOCKER_METADATA_SET_OUTPUT_ENV`     | Bool   | If `true`, sets each output as an environment variable (default `true`)                                                                      |\n\n## `context` input\n\n`context` defines where to get context metadata:\n\n```yaml\n# default\ncontext: workflow\n# or\ncontext: git\n```\n\n* `workflow`: Get context metadata from the workflow (GitHub context). See https://docs.github.com/en/actions/learn-github-actions/contexts#github-context\n* `git`: Get context metadata from the workflow and overrides some of them with current Git context, such as `ref` and `sha`.\n\n## `images` input\n\n`images` defines a list of Docker images to use as base name for [`tags`](#tags-input):\n\n```yaml\nimages: |\n  name/foo\n  ghcr.io/name/bar\n  # or\n  name=name/foo\n  name=ghcr.io/name/bar\n```\n\nExtended attributes and default values:\n\n```yaml\nimages: |\n  name=,enable=true\n```\n\n* `name=\u003cstring\u003e` image base name\n* `enable=\u003ctrue|false\u003e` enable this entry (default `true`)\n\nIf `images` is empty, tags will be generated without base name.\n\n## `flavor` input\n\n`flavor` defines a global behavior for [`tags`](#tags-input):\n\n```yaml\nflavor: |\n  latest=auto\n  prefix=\n  suffix=\n```\n\n* `latest=\u003cauto|true|false\u003e`: Handle [latest tag](#latest-tag) (default `auto`)\n* `prefix=\u003cstring\u003e,onlatest=\u003ctrue|false\u003e`: A global prefix for each generated\n  tag and optionally for `latest`\n* `suffix=\u003cstring\u003e,onlatest=\u003ctrue|false\u003e`: A global suffix for each generated\n  tag and optionally for `latest`\n\n## `tags` input\n\n`tags` is the core input of this action as everything related to it will\nreflect the output metadata. This one is in the form of a key-value pair list\nin CSV format to remove limitations intrinsically linked to GitHub Actions\n(only string format is handled in the input fields). Here is an example:\n\n```yaml\ntags: |\n  type=schedule\n  type=semver,pattern={{version}}\n  type=semver,pattern={{major}}.{{minor}}\n  type=semver,pattern={{major}}\n  type=ref,event=branch\n  type=ref,event=pr\n  type=sha\n```\n\nEach entry is defined by a `type`, which are:\n\n* [`type=schedule`](#typeschedule)\n* [`type=semver`](#typesemver)\n* [`type=pep440`](#typepep440)\n* [`type=match`](#typematch)\n* [`type=edge`](#typeedge)\n* [`type=ref`](#typeref)\n* [`type=raw`](#typeraw)\n* [`type=sha`](#typesha)\n\nAnd global attributes:\n\n* `enable=\u003ctrue|false\u003e` enable this entry (default `true`)\n* `priority=\u003cnumber\u003e` set tag [priority](#priority-attribute) order\n* `prefix=\u003cstring\u003e` add prefix\n* `suffix=\u003cstring\u003e` add suffix\n\nDefault entries if `tags` input is empty:\n\n```yaml\ntags: |\n  type=schedule\n  type=ref,event=branch\n  type=ref,event=tag\n  type=ref,event=pr\n```\n\n### `type=schedule`\n\n```yaml\ntags: |\n  # minimal\n  type=schedule\n  # default\n  type=schedule,pattern=nightly\n  # handlebars\n  type=schedule,pattern={{date 'YYYYMMDD'}}\n  # handlebars with timezone\n  type=schedule,pattern={{date 'YYYYMMDD-hhmmss' tz='Asia/Tokyo'}}\n```\n\nWill be used on [schedule event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).\n\n`pattern` is a specially crafted attribute to support [Handlebars' template](https://handlebarsjs.com/guide/)\nwith the following expressions:\n\n* `date 'format' tz='Timezone'` ; render date by its [moment format](https://momentjs.com/docs/#/displaying/format/).\n  Default `tz` is UTC.\n\n| Pattern                                      | Output            |\n|----------------------------------------------|-------------------|\n| `nightly`                                    | `nightly`         |\n| `{{date 'YYYYMMDD'}}`                        | `20200110`        |\n| `{{date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}` | `20200110-093000` |\n\nExtended attributes and default values:\n\n```yaml\ntags: |\n  type=schedule,enable=true,priority=1000,prefix=,suffix=,pattern=nightly\n```\n\n### `type=semver`\n\n```yaml\ntags: |\n  # minimal\n  type=semver,pattern={{version}}\n  # use custom value instead of git tag\n  type=semver,pattern={{version}},value=v1.0.0\n```\n\nWill be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)\nand requires a valid [semver](https://semver.org/) Git tag, but you can also\nuse a custom value through `value` attribute.\n\n`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/)\nwith the following expressions:\n\n* `raw` ; the actual tag\n* `version` ; shorthand for `{{major}}.{{minor}}.{{patch}}` (can include pre-release)\n* `major` ; major version identifier\n* `minor` ; minor version identifier\n* `patch` ; patch version identifier\n\n| Git tag            | Pattern                                                  | Output               |\n|--------------------|----------------------------------------------------------|----------------------|\n| `v1.2.3`           | `{{raw}}`                                                | `v1.2.3`             |\n| `v1.2.3`           | `{{version}}`                                            | `1.2.3`              |\n| `v1.2.3`           | `{{major}}.{{minor}}`                                    | `1.2`                |\n| `v1.2.3`           | `v{{major}}`                                             | `v1`                 |\n| `v1.2.3`           | `{{minor}}`                                              | `2`                  |\n| `v1.2.3`           | `{{patch}}`                                              | `3`                  |\n| `v2.0.8-beta.67`   | `{{raw}}`                                                | `v2.0.8-beta.67`     |\n| `v2.0.8-beta.67`   | `{{version}}`                                            | `2.0.8-beta.67`      |\n| `v2.0.8-beta.67`   | `{{major}}.{{minor}}`                                    | `2.0.8-beta.67`*     |\n\n\u003e *Pre-release (rc, beta, alpha) will only extend `{{version}}` (or `{{raw}}`\n\u003e if specified) as tag because they are updated frequently, and contain many\n\u003e breaking changes that are (by the author's design) not yet fit for public\n\u003e consumption.\n\nExtended attributes and default values:\n\n```yaml\ntags: |\n  type=semver,enable=true,priority=900,prefix=,suffix=,pattern=,value=\n```\n\n### `type=pep440`\n\n```yaml\ntags: |\n  # minimal\n  type=pep440,pattern={{version}}\n  # use custom value instead of git tag\n  type=pep440,pattern={{version}},value=1.0.0\n```\n\nWill be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)\nand requires a Git tag that conforms to [PEP 440](https://www.python.org/dev/peps/pep-0440/),\nbut you can also use a custom value through `value` attribute.\n\n`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/)\nwith the following expressions:\n\n* `raw` ; the actual tag\n* `version` ; cleaned version\n* `major` ; major version identifier\n* `minor` ; minor version identifier\n* `patch` ; patch version identifier\n\n| Git tag            | Pattern                                                  | Output               |\n|--------------------|----------------------------------------------------------|----------------------|\n| `1.2.3`            | `{{raw}}`                                                | `1.2.3`              |\n| `1.2.3`            | `{{version}}`                                            | `1.2.3`              |\n| `v1.2.3`           | `{{version}}`                                            | `1.2.3`              |\n| `1.2.3`            | `{{major}}.{{minor}}`                                    | `1.2`                |\n| `1.2.3`            | `v{{major}}`                                             | `v1`                 |\n| `v1.2.3rc2`        | `{{raw}}`                                                | `v1.2.3rc2`          |\n| `1.2.3rc2`         | `{{version}}`                                            | `1.2.3rc2`           |\n| `1.2.3rc2`         | `{{major}}.{{minor}}`                                    | `1.2.3rc2`*          |\n| `1.2.3post1`       | `{{major}}.{{minor}}`                                    | `1.2.3.post1`*       |\n| `1.2.3beta2`       | `{{major}}.{{minor}}`                                    | `1.2.3b2`*           |\n| `1.0dev4`          | `{{major}}.{{minor}}`                                    | `1.0.dev4`*          |\n\n\u003e *dev/pre/post release will only extend `{{version}}` (or `{{raw}}` if\n\u003e specified) as tag because they are updated frequently, and contain many\n\u003e breaking changes that are (by the author's design) not yet fit for public\n\u003e consumption.\n\nExtended attributes and default values:\n\n```yaml\ntags: |\n  type=pep440,enable=true,priority=900,prefix=,suffix=,pattern=,value=\n```\n\n### `type=match`\n\n```yaml\ntags: |\n  # minimal\n  type=match,pattern=\\d.\\d.\\d\n  # define match group\n  type=match,pattern=v(.*),group=1\n  # use custom value instead of git tag\n  type=match,pattern=v(.*),group=1,value=v1.0.0\n```\n\nCan create a regular expression for matching Git tag with a pattern and\ncapturing group. Will be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)\nbut, you can also use a custom value through `value` attribute.\n\n| Git tag                 | Pattern          | Group   | Output                 |\n|-------------------------|------------------|---------|------------------------|\n| `v1.2.3`                | `\\d.\\d.\\d`       | `0`     | `1.2.3`                |\n| `v2.0.8-beta.67`        | `v(.*)`          | `1`     | `2.0.8-beta.67`        |\n| `v2.0.8-beta.67`        | `v(\\d.\\d)`       | `1`     | `2.0`                  |\n| `20200110-RC2`          | `\\d+`            | `0`     | `20200110`             |\n| `p1/v1.2.3`             | `p1/v(\\d.\\d.\\d)` | `1`     | `1.2.3`                |\n\nExtended attributes and default values:\n\n```yaml\ntags: |\n  type=match,enable=true,priority=800,prefix=,suffix=,pattern=,group=0,value=\n```\n\n### `type=edge`\n\n```yaml\ntags: |\n  # minimal\n  type=edge\n  # define default branch\n  type=edge,branch=main\n```\n\nAn `edge` tag reflects the last commit of the active branch on your Git\nrepository. I usually prefer to use `edge` as a Docker tag for a better\ndistinction or common pattern. This is also used by official images like [Alpine](https://hub.docker.com/_/alpine).\n\nExtended attributes and default values:\n\n```yaml\ntags: |\n  type=edge,enable=true,priority=700,prefix=,suffix=,branch=$repo.default_branch\n```\n\n### `type=ref`\n\n```yaml\ntags: |\n  # branch event\n  type=ref,event=branch\n  # tag event\n  type=ref,event=tag\n  # pull request event\n  type=ref,event=pr\n```\n\nThis type handles Git ref (or reference) for the following events:\n\n* `branch` ; eg. `refs/heads/master`\n* `tag` ; eg. `refs/tags/v1.0.0`\n* `pr` ; eg. `refs/pull/318/merge`\n\n| Event               | Ref                           | Output           |\n|---------------------|-------------------------------|------------------|\n| `pull_request`      | `refs/pull/2/merge`           | `pr-2`           |\n| `push`              | `refs/heads/master`           | `master`         |\n| `push`              | `refs/heads/my/branch`        | `my-branch`      |\n| `push tag`          | `refs/tags/v1.2.3`            | `v1.2.3`         |\n| `push tag`          | `refs/tags/v2.0.8-beta.67`    | `v2.0.8-beta.67` |\n| `workflow_dispatch` | `refs/heads/master`           | `master`         |\n\nExtended attributes and default values:\n\n```yaml\ntags: |\n  # branch event\n  type=ref,enable=true,priority=600,prefix=,suffix=,event=branch\n  # tag event\n  type=ref,enable=true,priority=600,prefix=,suffix=,event=tag\n  # pull request event\n  type=ref,enable=true,priority=600,prefix=pr-,suffix=,event=pr\n```\n\n### `type=raw`\n\n```yaml\ntags: |\n  type=raw,value=foo\n  type=raw,value=bar\n  # or\n  type=raw,foo\n  type=raw,bar\n  # or\n  foo\n  bar\n```\n\nOutput custom tags according to your needs.\n\nExtended attributes and default values:\n\n```yaml\ntags: |\n  type=raw,enable=true,priority=200,prefix=,suffix=,value=\n```\n\n### `type=sha`\n\n```yaml\ntags: |\n  # minimal (short sha)\n  type=sha\n  # full length sha\n  type=sha,format=long\n```\n\nOutput Git short commit (or long if specified) as Docker tag like\n`sha-860c190`.\n\nBy default, the length of the short commit SHA is `7` characters. You can\nincrease this length for larger repositories by setting the\n[`DOCKER_METADATA_SHORT_SHA_LENGTH` environment variable](#environment-variables):\n\n```yaml\n      -\n        name: Docker meta\n        id: meta\n        uses: docker/metadata-action@v5\n        with:\n          images: |\n            name/app\n          tags: |\n            type=sha\n        env:\n          DOCKER_METADATA_SHORT_SHA_LENGTH: 12\n```\n\nExtended attributes and default values:\n\n```yaml\ntags: |\n  type=sha,enable=true,priority=100,prefix=sha-,suffix=,format=short\n```\n\n## Notes\n\n### Image name and tag sanitization\n\nIn order to comply with [the specification](https://docs.docker.com/engine/reference/commandline/tag/#description),\nthe image name components may contain lowercase letters, digits and separators.\nA separator is defined as a period, one or two underscores, or one or more\ndashes. A name component may not start or end with a separator.\n\nA tag name must be a valid ASCII chars sequences and may contain lowercase and\nuppercase letters, digits, underscores, periods and dashes. A tag name may not\nstart with a period or a dash and may contain a maximum of 128 characters.\n\nTo ease the integration in your workflow, this action will automatically:\n\n* Lowercase the image name\n* Replace invalid chars sequences with `-` for tags\n\n### Latest tag\n\n`latest` tag is handled through the [`flavor` input](#flavor-input). It will be\ngenerated by default (`auto` mode) for:\n\n* [`type=ref,event=tag`](#typeref)\n* [`type=semver,pattern=...`](#typesemver)\n* [`type=pep440,pattern=...`](#typepep440)\n* [`type=match,pattern=...`](#typematch)\n\nFor conditionally tagging with latest for a specific branch name, e.g. if your\ndefault branch name is not `master`, use `type=raw` with a boolean expression:\n\n```yaml\ntags: |\n  # set latest tag for master branch\n  type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'master') }}\n```\n\nYou can also use the [`{{is_default_branch}}` global expression](#is_default_branch)\nto conditionally tag with latest for the default branch:\n\n```yaml\ntags: |\n  # set latest tag for default branch\n  type=raw,value=latest,enable={{is_default_branch}}\n```\n\n### `priority` attribute\n\n`priority=\u003cint\u003e` attribute is used to sort tags in the final list. The higher\nthe value, the higher the priority. The first tag in the list (higher priority)\nwill be used as the image version for generated OCI label and [`version` output](#outputs).\nEach tags `type` attribute has a default priority:\n\n| Attribute  | Default priority |\n|------------|------------------|\n| `schedule` | `1000`           |\n| `semver`   | `900`            |\n| `pep440`   | `900`            |\n| `match`    | `800`            |\n| `edge`     | `700`            |\n| `ref`      | `600`            |\n| `raw`      | `200`            |\n| `sha`      | `100`            |\n\n### Global expressions\n\nThe following [Handlebars' template](https://handlebarsjs.com/guide/) expressions\nfor `prefix`, `suffix`, `value` and `enable` attributes of `tags` input are\navailable:\n\n```yaml\ntags: |\n  # dynamically set the branch name as a prefix\n  type=sha,prefix={{branch}}-\n  # dynamically set the branch name and sha as a custom tag\n  type=raw,value=mytag-{{branch}}-{{sha}}\n```\n\nThey can also be applied to `labels` and `annotations` inputs:\n\n```yaml\nlabels: |\n  org.opencontainers.image.created={{commit_date 'YYYY-MM-DDTHH:mm:ss.SSS[Z]'}}\n```\n\n#### `{{branch}}`\n\nReturns the branch name that triggered the workflow run. Will be empty if not \na branch reference:\n\n| Event          | Ref                    | Output      |\n|----------------|------------------------|-------------|\n| `pull_request` | `refs/pull/2/merge`    |             |\n| `push`         | `refs/heads/master`    | `master`    |\n| `push`         | `refs/heads/my/branch` | `my-branch` |\n| `push tag`     | `refs/tags/v1.2.3`     |             |\n\n#### `{{tag}}`\n\nReturns the tag name that triggered the workflow run. Will be empty if not a\ntag reference:\n\n| Event           | Ref                           | Output             |\n|-----------------|-------------------------------|--------------------|\n| `pull_request`  | `refs/pull/2/merge`           |                    |\n| `push`          | `refs/heads/master`           |                    |\n| `push`          | `refs/heads/my/branch`        |                    |\n| `push tag`      | `refs/tags/v1.2.3`            | `v1.2.3`           |\n\n#### `{{sha}}`\n\nReturns the short commit SHA that triggered the workflow run (e.g., `90dd603`).\n\n#### `{{base_ref}}`\n\nReturns the base ref or target branch of the pull request that triggered the\nworkflow run. Will be empty for a branch reference:\n\n| Event          | Ref                           | Output             |\n|----------------|-------------------------------|--------------------|\n| `pull_request` | `refs/pull/2/merge`           | `master`           |\n| `push`         | `refs/heads/master`           |                    |\n| `push`         | `refs/heads/my/branch`        |                    |\n| `push tag`*    | `refs/tags/v1.2.3`            | `master`           |\n\n\u003e *`base_ref` is available in the push payload but doesn't always seem to \n\u003e return the expected branch when the push tag event occurs. It's also\n\u003e [not documented in GitHub docs](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#push).\n\u003e We keep it for backward compatibility, but it's **not recommended relying on it**.\n\u003e More context in [#192](https://github.com/docker/metadata-action/pull/192#discussion_r854673012). \n\n#### `{{is_default_branch}}`\n\nReturns `true` if the branch that triggered the workflow run is the default\none, otherwise `false`.\n\n#### `{{date '\u003cformat\u003e' tz='\u003ctimezone\u003e'}}`\n\nReturns the current date rendered by its [moment format](https://momentjs.com/docs/#/displaying/format/).\nDefault `tz` is UTC.\n\n| Expression                                   | Output example                          |\n|----------------------------------------------|-----------------------------------------|\n| `{{date 'YYYYMMDD'}}`                        | `20200110`                              |\n| `{{date 'dddd, MMMM Do YYYY, h:mm:ss a'}}`   | `Friday, January 10th 2020, 3:25:50 pm` |\n| `{{date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}` | `20200110-093000`                       |\n\n#### `{{commit_date '\u003cformat\u003e' tz='\u003ctimezone\u003e'}}`\n\nReturns the date when the current git commit is committed, rendered by its\n[moment format](https://momentjs.com/docs/#/displaying/format/). It falls back\nto the current date if the commit date is not available.\n\nDefault `tz` is UTC.\n\n| Expression                                          | Output example                          |\n|-----------------------------------------------------|-----------------------------------------|\n| `{{commit_date 'YYYYMMDD'}}`                        | `20200110`                              |\n| `{{commit_date 'dddd, MMMM Do YYYY, h:mm:ss a'}}`   | `Friday, January 10th 2020, 3:25:50 pm` |\n| `{{commit_date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}` | `20200110-093000`                       |\n\n### Major version zero\n\nMajor version zero (`0.y.z`) is for initial development and **may** change at\nany time. This means the public API [**should not** be considered stable](https://semver.org/#spec-item-4).\n\nIn this case, Docker tag `0` **should not** be generated if you're using [`type=semver`](#typesemver)\nwith `{{major}}` pattern. You can manage this behavior like this:\n\n```yaml\n# refs/tags/v0.1.2\ntags: |\n  # output 0.1.2\n  type=semver,pattern={{version}}\n  # output 0.1\n  type=semver,pattern={{major}}.{{minor}}\n  # disabled if major zero\n  type=semver,pattern={{major}},enable=${{ !startsWith(github.ref, 'refs/tags/v0.') }}\n```\n\n### JSON output object\n\nThe `json` output is a JSON object composed of the generated tags and labels so\nthat you can reuse them further in your workflow using the [`fromJSON` function](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson):\n\n```yaml\n      -\n        name: Docker meta\n        uses: docker/metadata-action@v5\n        id: meta\n        with:\n          images: name/app\n      -\n        name: Build and push\n        uses: docker/build-push-action@v6\n        with:\n          tags: ${{ steps.meta.outputs.tags }}\n          labels: ${{ steps.meta.outputs.labels }}\n          build-args: |\n            BUILDTIME=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.created'] }}\n            VERSION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.version'] }}\n            REVISION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}\n```\n\n### Overwrite labels and annotations\n\nIf some [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)\ngenerated are not suitable as labels/annotations, you can overwrite them like\nthis:\n\n```yaml\n      -\n        name: Docker meta\n        id: meta\n        uses: docker/metadata-action@v5\n        with:\n          images: name/app\n          labels: |\n            maintainer=CrazyMax\n            org.opencontainers.image.title=MyCustomTitle\n            org.opencontainers.image.description=Another description\n            org.opencontainers.image.vendor=MyCompany\n```\n\n### Annotations\n\nSince Buildx 0.12, it is possible to set annotations to your image through the\n`--annotation` flag.\n\nWith the [`build-push-action`](https://github.com/docker/build-push-action/),\nyou can set the `annotations` input with the value of the `annotations` output\nof the `metadata-action`:\n\n```yaml\n      -\n        name: Docker meta\n        uses: docker/metadata-action@v5\n        with:\n          images: name/app\n      -\n        name: Build and push\n        uses: docker/build-push-action@v6\n        with:\n          tags: ${{ steps.meta.outputs.tags }}\n          annotations: ${{ steps.meta.outputs.annotations }}\n```\n\nThe same can be done with the [`bake-action`](https://github.com/docker/bake-action/):\n\n```yaml\n      -\n        name: Docker meta\n        uses: docker/metadata-action@v5\n        with:\n          images: name/app\n      -\n        name: Build\n        uses: docker/bake-action@v6\n        with:\n          files: |\n            ./docker-bake.hcl\n            cwd://${{ steps.meta.outputs.bake-file-tags }}\n            cwd://${{ steps.meta.outputs.bake-file-annotations }}\n          targets: build\n```\n\nNote that annotations can be attached at many different levels within a manifest.\nBy default, the generated annotations will be attached to image manifests,\nbut different registries may expect annotations at different places;\na common practice is to read annotations at _image indexes_ if present,\nwhich are often used by multi-arch builds to index platform-specific images.\nIf you want to specify level(s) for your annotations, you can use the\n[`DOCKER_METADATA_ANNOTATIONS_LEVELS` environment variable](#environment-variables)\nwith a comma separated list of all levels the annotations should be attached to (defaults to `manifest`).\nThe following configuration demonstrates the ability to attach annotations to both image manifests and image indexes,\nthough your registry may only need annotations at the index level. (That is, `index` alone may be enough.)\nPlease consult the documentation of your registry.\n\n```yaml\n      -\n        name: Docker meta\n        uses: docker/metadata-action@v5\n        with:\n          images: name/app\n        env:\n          DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index\n      -\n        name: Build and push\n        uses: docker/build-push-action@v6\n        with:\n          tags: ${{ steps.meta.outputs.tags }}\n          annotations: ${{ steps.meta.outputs.annotations }}\n```\n\nMore information about annotations in the [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md).\n\n## Contributing\n\nWant to contribute? Awesome! You can find information about contributing to\nthis project in the [CONTRIBUTING.md](/.github/CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocker%2Fmetadata-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocker%2Fmetadata-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocker%2Fmetadata-action/lists"}