repository·master·Indexed 22 days ago
https://github.com/docker/metadata-actionA GitHub Action that extracts metadata (tags and labels) from Git references and GitHub events to simplify Docker image tagging and labeling in CI/CD workflows. It supports Semantic Versioning (Semver), PEP 440, regex-based matching, and integration with docker/build-push-action and docker/bake-action.
The action automatically ensures image names and tags comply with Docker specifications:
- to ensure compliance with ASCII requirements and length limits (max 128 characters).The priority=<int> attribute determines the order of tags in the final list. A higher value indicates higher priority.
Crucially, the first tag in the sorted list (the one with the highest priority) is used as the image version for the generated OCI labels and the version output.
Default priorities by type:
| Attribute | Default priority |
|---|---|
schedule | 1000 |
semver | 900 |
pep440 | 900 |
match | 800 |
edge | 700 |
ref | 600 |
raw | 200 |
sha | 100 |
The latest tag is generated by default for ref, semver, pep440, and match types. To conditionally apply a latest tag based on specific logic, use type=raw with the enable attribute.
Using the default branch:
Use the {{is_default_branch}} global expression to tag the default branch as latest.
Using a specific branch name:
Use a boolean expression to check the github.ref.
# set latest tag for default branch
tags: |
type=raw,value=latest,enable={{is_default_branch}}
# set latest tag for master branch
tags: |
type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'master') }}The docker/metadata-action extracts metadata (tags and labels) from Git references and GitHub events. In a basic configuration, you provide the images input, and the action automatically generates tags based on the event type (e.g., master for pushes to the master branch, pr-X for pull requests, and latest for tag pushes).
This is commonly used in conjunction with docker/login-action and docker/build-push-action to automate image tagging and labeling.
name: ci
on: [push, pull_request]
jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Docker meta
id: meta
uses: docker/metadata-action@v6
with:
images: name/app
-
name: Login to DockerHub
if: github.event_name != 'pull_request'
uses: docker/login-action@v4
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v7
with:
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}You can customize tag generation using the tags input. For Semantic Versioning (Semver), you can define patterns to automatically create versioned tags, major/minor tags, and latest tags.
Common tag types include:
type=ref,event=branch: Uses the branch name.type=ref,event=pr: Uses the pull request number.type=semver,pattern={{version}}: Uses the full semver tag.type=semver,pattern={{major}}.{{minor}}: Uses the major.minor version.type=sha: Uses the git commit SHA. -
name: Docker meta
id: meta
uses: docker/metadata-action@v6
with:
images: |
name/app
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}The action supports generating a Bake definition file that can be consumed by docker/bake-action.
To use this:
docker-bake.hcl file, declare an empty target named docker-metadata-action and have your build targets inherit from it.${{ steps.meta.outputs.bake-file }} output in your workflow to provide the path to the generated Bake file.The generated Bake file contains a JSON object mapping the docker-metadata-action target to the calculated tags, labels, and args (like DOCKER_META_IMAGES and DOCKER_META_VERSION).
// 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: Build
uses: docker/bake-action@v7
with:
files: |
./docker-bake.hcl
cwd://${{ steps.meta.outputs.bake-file }}
targets: buildWhen using type=semver, you may want to prevent the generation of a 0 tag during initial development. You can use the enable attribute with a boolean expression to check if the version starts with v0..
# 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.') }}Since Buildx 0.12, you can set annotations in your image. You can pass the annotations output from metadata-action directly to docker/build-push-action or docker/bake-action.
Controlling Annotation Levels:
By default, annotations are attached to the image manifest. If your registry requires annotations at different levels (e.g., at the image index level for multi-arch builds), use the DOCKER_METADATA_ANNOTATIONS_LEVELS environment variable with a comma-separated list of levels (e.g., manifest,index).
-
name: Docker meta
uses: docker/metadata-action@v6
with:
images: name/app
env:
DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
-
name: Build and push
uses: docker/build-push-action@v7
with:
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}By default, on pull_request or pull_request_target events, the action uses the commit SHA that triggered the workflow.
If you want the action to use the SHA of the head branch (the source branch of the PR) instead, set the environment variable DOCKER_METADATA_PR_HEAD_SHA to true.
- uses: docker/metadata-action@v6
env:
DOCKER_METADATA_PR_HEAD_SHA: trueThe metadata-action uses different Type categories to classify how Docker image tags are generated. Each type has a default priority value; when multiple tags are generated, they are sorted by priority (higher numbers take precedence).
schedule: For scheduled builds (e.g., nightly).semver: Semantic versioning patterns.pep440: Python PEP 440 versioning patterns.match: Regex-based matching.edge: For branch-based or rolling tags.ref: Based on GitHub events like branch, tag, or pr.raw: Literal string values.sha: Git commit SHA identifiers.| Type | Priority | Note |
|---|---|---|
schedule | 1000 | Highest priority |
semver | 900 | |
pep440 | 900 | |
match | 800 | |
edge | 700 | |
ref | 600 | |
raw | 200 | |
sha | 100 | Lowest priority |
The tags input is the core configuration for docker/metadata-action. It accepts a list of key-value pairs in CSV format, where each entry defines a tag generation rule via a type.
If the tags input is left empty, the action defaults to:
tags: |
type=schedule
type=ref,event=branch
type=ref,event=tag
type=ref,event=prEach entry can be customized with global attributes:
enable=<true|false>: Enables or disables the entry (default: true).priority=<number>: Sets the order of the tags.prefix=<string>: Adds a prefix to the generated tag.suffix=<string>: Adds a suffix to the generated tag.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=shaThe flavor input allows you to define global behaviors for how tags are generated, such as handling the latest tag or adding prefixes and suffixes.
latest=<auto|true|false>: Controls how the latest tag is handled (default is auto).prefix=<string>,onlatest=<true|false>: Adds a global prefix to all tags. onlatest determines if the prefix applies to the latest tag.suffix=<string>,onlatest=<true|false>: Adds a global suffix to all tags. onlatest determines if the suffix applies to the latest tag.flavor: |
latest=auto
prefix=
suffix=