docker/metadata-action

Generate Docker tags and OCI labels automatically from git refs and events.

Official actionCategory: Docker & ContainersLatest v5View on GitHub

What it does

docker/metadata-action reads the git context and produces a consistent set of tags (latest, semver, sha, branch) and OCI labels that you feed into docker/build-push-action.

It removes brittle, hand-written tag expressions from your workflow.

Usage

workflow (.yml)

steps:
  - id: meta
    uses: docker/metadata-action@v5
    with:
      images: myorg/app
      tags: |
        type=semver,pattern={{version}}
        type=sha
  - uses: docker/build-push-action@v6
    with:
      push: true
      tags: ${{ steps.meta.outputs.tags }}
      labels: ${{ steps.meta.outputs.labels }}

Inputs

Input	Description	Default	Required
`images`	Base image name(s) to tag.	-	Yes
`tags`	Tag rules, e.g. type=semver,pattern={{version}}.	`defaults`	No
`flavor`	Global tag flavor, e.g. latest=auto.	-	No
`labels`	Custom OCI labels to add.	-	No

Outputs

Output	Description
`tags`	Generated tags, newline separated.
`labels`	Generated OCI labels.
`version`	The primary version tag.
`json`	All metadata as JSON.

Notes

Reference the outputs by the step id, e.g. steps.meta.outputs.tags.

Common errors

Empty tags usually mean the trigger did not match any tag rule (for example a type=semver rule on a branch push, not a tag push).

Security and pinning

Pin to a commit SHA.

Alternatives and related

docker/build-push-actionBuild and push a Docker image using Buildx, with cache and multi-platform support.

Frequently asked questions

How do I tag images with the semver from a git tag?

Add type=semver,pattern={{version}} under tags and push a git tag like v1.2.3.