docker/metadata-action
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

mirror docker/metadata-action@v5

Browse Source
This commit is contained in:
action-mirror
2026-09-13 22:53:39 +08:00
parent 22022ded36
commit e8985e2108
43 changed files with 10240 additions and 6207 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+236 -75
View File
@@ -44,10 +44,13 @@ ___
* [`{{sha}}`](#sha)
* [`{{base_ref}}`](#base_ref)
* [`{{is_default_branch}}`](#is_default_branch)
* [`{{is_not_default_branch}}`](#is_not_default_branch)
* [`{{date '<format>' tz='<timezone>'}}`](#date-format-tztimezone)
* [`{{commit_date '<format>' tz='<timezone>'}}`](#commit_date-format-tztimezone)
* [Major version zero](#major-version-zero)
* [JSON output object](#json-output-object)
* [Overwrite labels](#overwrite-labels)
* [Overwrite labels and annotations](#overwrite-labels-and-annotations)
* [Annotations](#annotations)
* [Contributing](#contributing)
## Usage
@@ -74,23 +77,23 @@ jobs:
steps:
-
name: Checkout
uses: actions/checkout@v3
uses: actions/checkout@v5
-
name: Docker meta
id: meta
uses: docker/metadata-action@v4
uses: docker/metadata-action@v5
with:
images: name/app
-
name: Login to DockerHub
if: github.event_name != 'pull_request'
uses: docker/login-action@v2
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v4
uses: docker/build-push-action@v6
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
@@ -128,11 +131,11 @@ jobs:
steps:
-
name: Checkout
uses: actions/checkout@v3
uses: actions/checkout@v5
-
name: Docker meta
id: meta
uses: docker/metadata-action@v4
uses: docker/metadata-action@v5
with:
images: |
name/app
@@ -144,13 +147,13 @@ jobs:
-
name: Login to DockerHub
if: github.event_name != 'pull_request'
uses: docker/login-action@v2
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v4
uses: docker/build-push-action@v6
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
@@ -204,13 +207,10 @@ jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
uses: actions/checkout@v3
-
name: Docker meta
id: meta
uses: docker/metadata-action@v4
uses: docker/metadata-action@v5
with:
images: |
name/app
@@ -222,16 +222,16 @@ jobs:
type=sha
-
name: Build
uses: docker/bake-action@v2
uses: docker/bake-action@v6
with:
files: |
./docker-bake.hcl
${{ steps.meta.outputs.bake-file }}
cwd://${{ 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:
Content of `${{ steps.meta.outputs.bake-file }}` file, combining tags and
labels, will look like this with `refs/tags/v1.2.3` ref:
```json
{
@@ -262,12 +262,29 @@ Content of `${{ steps.meta.outputs.bake-file }}` file will look like this with
}
```
You can also use the `bake-file-tags` and `bake-file-labels` outputs if you
just want to use tags and/or labels respectively. The following example is
similar to the previous one:
```yaml
-
name: Build
uses: docker/bake-action@v6
with:
files: |
./docker-bake.hcl
cwd://${{ steps.meta.outputs.bake-file-tags }}
cwd://${{ steps.meta.outputs.bake-file-labels }}
targets: build
```
## Customizing
### inputs
Following inputs can be used as `step.with` keys
The following inputs can be used as `step.with` keys:
> [!NOTE]
> `List` type is a newline-delimited string
> ```yaml
> labels: |
@@ -276,41 +293,50 @@ Following inputs can be used as `step.with` keys
> org.opencontainers.image.vendor=MyCompany
> ```
| Name | Type | Description |
|---------------------|--------|-------------------------------------------------------------------------------|
| `context` | String | Where to get context data. Allowed options are: `workflow` (default), `git`. |
| `images` | List | List of Docker images to use as base name for tags |
| `tags` | List | List of [tags](#tags-input) as key-value pair attributes |
| `flavor` | List | [Flavor](#flavor-input) to apply |
| `labels` | List | List of custom labels |
| `sep-tags` | String | Separator to use for tags output (default `\n`) |
| `sep-labels` | String | Separator to use for labels output (default `\n`) |
| `bake-target` | String | Bake target name (default `docker-metadata-action`) |
| Name | Type | Description |
|-------------------|--------|------------------------------------------------------------------------------|
| `context` | String | Where to get context data. Allowed options are: `workflow` (default), `git`. |
| `images` | List | List of Docker images to use as base name for tags |
| `tags` | List | List of [tags](#tags-input) as key-value pair attributes |
| `flavor` | List | [Flavor](#flavor-input) to apply |
| `labels` | List | List of custom labels |
| `annotations` | List | List of custom annotations |
| `sep-tags` | String | Separator to use for tags output (default `\n`) |
| `sep-labels` | String | Separator to use for labels output (default `\n`) |
| `sep-annotations` | String | Separator to use for annotations output (default `\n`) |
| `bake-target` | String | Bake target name (default `docker-metadata-action`) |
### outputs
Following outputs are available
The following outputs are available:
| Name | Type | Description |
|---------------|---------|--------------------------------------------------------------------------------------------|
| `version` | String | Docker image version |
| `tags` | String | Docker tags |
| `labels` | String | Docker labels |
| `json` | String | JSON output of tags and labels |
| `bake-file` | File | [Bake file definition](https://docs.docker.com/build/customize/bake/file-definition/) path |
| Name | Type | Description |
|-------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `version` | String | Docker image version |
| `tags` | String | Docker tags |
| `tag-names` | String | Docker tag names without image base name |
| `labels` | String | Docker labels |
| `annotations` | String | [Annotations](https://github.com/moby/buildkit/blob/master/docs/annotations.md) |
| `json` | String | JSON output of tags and labels |
| `bake-file-tags` | File | [Bake file definition](https://docs.docker.com/build/bake/reference/) path with tags |
| `bake-file-labels` | File | [Bake file definition](https://docs.docker.com/build/bake/reference/) path with labels |
| `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) |
Alternatively, each output is also exported as an environment variable:
Alternatively, each output is also exported as an environment variable when `DOCKER_METADATA_SET_OUTPUT_ENV` is `true`:
* `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`
* `DOCKER_METADATA_OUTPUT_BAKE_FILE_TAGS`
* `DOCKER_METADATA_OUTPUT_BAKE_FILE_LABELS`
* `DOCKER_METADATA_OUTPUT_BAKE_FILE_ANNOTATIONS`
So it can be used with our [Docker Build Push action](https://github.com/docker/build-push-action/):
```yaml
- uses: docker/build-push-action@v4
- uses: docker/build-push-action@v6
with:
build-args: |
DOCKER_METADATA_OUTPUT_JSON
@@ -318,9 +344,12 @@ So it can be used with our [Docker Build Push action](https://github.com/docker/
### environment variables
| Name | Type | Description |
|-------------------------------|------|------------------------------------------------------------------------------------------------------------|
| `DOCKER_METADATA_PR_HEAD_SHA` | Bool | If `true`, set associated head SHA instead of commit SHA that triggered the workflow on pull request event |
| Name | Type | Description |
|--------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------|
| `DOCKER_METADATA_PR_HEAD_SHA` | Bool | If `true`, set associated head SHA instead of commit SHA that triggered the workflow on pull request event |
| `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. |
| `DOCKER_METADATA_ANNOTATIONS_LEVELS` | String | Comma separated list of annotations levels to set for annotations output separated (default `manifest`) |
| `DOCKER_METADATA_SET_OUTPUT_ENV` | Bool | If `true`, sets each output as an environment variable (default `true`) |
## `context` input
@@ -359,6 +388,8 @@ images: |
* `name=<string>` image base name
* `enable=<true|false>` enable this entry (default `true`)
If `images` is empty, tags will be generated without base name.
## `flavor` input
`flavor` defines a global behavior for [`tags`](#tags-input):
@@ -433,7 +464,7 @@ tags: |
# handlebars
type=schedule,pattern={{date 'YYYYMMDD'}}
# handlebars with timezone
type=schedule,pattern={{date 'YYYYMMDD-hhmmss' tz='Asia/Tokyo'}}
type=schedule,pattern={{date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}
```
Will be used on [schedule event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
@@ -465,6 +496,8 @@ tags: |
type=semver,pattern={{version}}
# use custom value instead of git tag
type=semver,pattern={{version}},value=v1.0.0
# use custom value and match part of it
type=semver,pattern={{version}},value=p1/v1.0.0,match=v(\d.\d.\d)$
```
Will be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
@@ -480,18 +513,21 @@ with the following expressions:
* `minor` ; minor version identifier
* `patch` ; patch version identifier
| Git tag | Pattern | Output |
|--------------------|----------------------------------------------------------|----------------------|
| `v1.2.3` | `{{raw}}` | `v1.2.3` |
| `v1.2.3` | `{{version}}` | `1.2.3` |
| `v1.2.3` | `{{major}}.{{minor}}` | `1.2` |
| `v1.2.3` | `v{{major}}` | `v1` |
| `v1.2.3` | `{{minor}}` | `2` |
| `v1.2.3` | `{{patch}}` | `3` |
| `v2.0.8-beta.67` | `{{raw}}` | `v2.0.8-beta.67` |
| `v2.0.8-beta.67` | `{{version}}` | `2.0.8-beta.67` |
| `v2.0.8-beta.67` | `{{major}}.{{minor}}` | `2.0.8-beta.67`* |
| Git tag | Pattern | Match | Output |
|------------------|-----------------------|----------------|------------------|
| `v1.2.3` | `{{raw}}` | | `v1.2.3` |
| `v1.2.3` | `{{version}}` | | `1.2.3` |
| `v1.2.3` | `{{major}}.{{minor}}` | | `1.2` |
| `v1.2.3` | `v{{major}}` | | `v1` |
| `v1.2.3` | `{{minor}}` | | `2` |
| `v1.2.3` | `{{patch}}` | | `3` |
| `p1/v1.2.3` | `{{version}}` | `v(\d.\d.\d)$` | `1.2.3` |
| `v2.0.8-beta.67` | `{{raw}}` | | `v2.0.8-beta.67` |
| `v2.0.8-beta.67` | `{{version}}` | | `2.0.8-beta.67` |
| `v2.0.8-beta.67` | `{{major}}` | | `2.0.8-beta.67`* |
| `v2.0.8-beta.67` | `{{major}}.{{minor}}` | | `2.0.8-beta.67`* |
> [!IMPORTANT]
> *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
@@ -501,7 +537,7 @@ Extended attributes and default values:
```yaml
tags: |
type=semver,enable=true,priority=900,prefix=,suffix=,pattern=,value=
type=semver,enable=true,priority=900,prefix=,suffix=,pattern=,value=,match=
```
### `type=pep440`
@@ -512,6 +548,8 @@ tags: |
type=pep440,pattern={{version}}
# use custom value instead of git tag
type=pep440,pattern={{version}},value=1.0.0
# use custom value and match part of it
type=pep440,pattern={{version}},value=p1/v1.0.0,match=v(\d.\d.\d)$
```
Will be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
@@ -527,20 +565,22 @@ with the following expressions:
* `minor` ; minor version identifier
* `patch` ; patch version identifier
| Git tag | Pattern | Output |
|--------------------|----------------------------------------------------------|----------------------|
| `1.2.3` | `{{raw}}` | `1.2.3` |
| `1.2.3` | `{{version}}` | `1.2.3` |
| `v1.2.3` | `{{version}}` | `1.2.3` |
| `1.2.3` | `{{major}}.{{minor}}` | `1.2` |
| `1.2.3` | `v{{major}}` | `v1` |
| `v1.2.3rc2` | `{{raw}}` | `v1.2.3rc2` |
| `1.2.3rc2` | `{{version}}` | `1.2.3rc2` |
| `1.2.3rc2` | `{{major}}.{{minor}}` | `1.2.3rc2`* |
| `1.2.3post1` | `{{major}}.{{minor}}` | `1.2.3.post1`* |
| `1.2.3beta2` | `{{major}}.{{minor}}` | `1.2.3b2`* |
| `1.0dev4` | `{{major}}.{{minor}}` | `1.0.dev4`* |
| Git tag | Pattern | Match | Output |
|--------------|-----------------------|----------------|----------------|
| `1.2.3` | `{{raw}}` | | `1.2.3` |
| `1.2.3` | `{{version}}` | | `1.2.3` |
| `v1.2.3` | `{{version}}` | | `1.2.3` |
| `1.2.3` | `{{major}}.{{minor}}` | | `1.2` |
| `1.2.3` | `v{{major}}` | | `v1` |
| `v1.2.3rc2` | `{{raw}}` | | `v1.2.3rc2` |
| `1.2.3rc2` | `{{version}}` | | `1.2.3rc2` |
| `p1/v1.2.3` | `{{version}}` | `v(\d.\d.\d)$` | `1.2.3` |
| `1.2.3rc2` | `{{major}}.{{minor}}` | | `1.2.3rc2`* |
| `1.2.3post1` | `{{major}}.{{minor}}` | | `1.2.3.post1`* |
| `1.2.3beta2` | `{{major}}.{{minor}}` | | `1.2.3b2`* |
| `1.0dev4` | `{{major}}.{{minor}}` | | `1.0.dev4`* |
> [!IMPORTANT]
> *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
@@ -677,7 +717,26 @@ tags: |
type=sha,format=long
```
Output Git short commit (or long if specified) as Docker tag like `sha-ad132f5`.
Output Git short commit (or long if specified) as Docker tag like
`sha-860c190`.
By default, the length of the short commit SHA is `7` characters. You can
increase this length for larger repositories by setting the
[`DOCKER_METADATA_SHORT_SHA_LENGTH` environment variable](#environment-variables):
```yaml
-
name: Docker meta
id: meta
uses: docker/metadata-action@v5
with:
images: |
name/app
tags: |
type=sha
env:
DOCKER_METADATA_SHORT_SHA_LENGTH: 12
```
Extended attributes and default values:
@@ -711,6 +770,7 @@ generated by default (`auto` mode) for:
* [`type=ref,event=tag`](#typeref)
* [`type=semver,pattern=...`](#typesemver)
* [`type=pep440,pattern=...`](#typepep440)
* [`type=match,pattern=...`](#typematch)
For conditionally tagging with latest for a specific branch name, e.g. if your
@@ -752,7 +812,8 @@ Each tags `type` attribute has a default priority:
### Global expressions
The following [Handlebars' template](https://handlebarsjs.com/guide/) expressions
for `prefix`, `suffix`, `value` and `enable` attributes are available:
for `prefix`, `suffix`, `value` and `enable` attributes of `tags` input are
available:
```yaml
tags: |
@@ -762,6 +823,13 @@ tags: |
type=raw,value=mytag-{{branch}}-{{sha}}
```
They can also be applied to `labels` and `annotations` inputs:
```yaml
labels: |
org.opencontainers.image.created={{commit_date 'YYYY-MM-DDTHH:mm:ss.SSS[Z]'}}
```
#### `{{branch}}`
Returns the branch name that triggered the workflow run. Will be empty if not
@@ -802,6 +870,7 @@ workflow run. Will be empty for a branch reference:
| `push` | `refs/heads/my/branch` | |
| `push tag`* | `refs/tags/v1.2.3` | `master` |
> [!IMPORTANT]
> *`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](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#push).
@@ -813,6 +882,11 @@ workflow run. Will be empty for a branch reference:
Returns `true` if the branch that triggered the workflow run is the default
one, otherwise `false`.
#### `{{is_not_default_branch}}`
Returns `true` if the branch that triggered the workflow run is not the default
one, otherwise `false`.
#### `{{date '<format>' tz='<timezone>'}}`
Returns the current date rendered by its [moment format](https://momentjs.com/docs/#/displaying/format/).
@@ -824,6 +898,20 @@ Default `tz` is UTC.
| `{{date 'dddd, MMMM Do YYYY, h:mm:ss a'}}` | `Friday, January 10th 2020, 3:25:50 pm` |
| `{{date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}` | `20200110-093000` |
#### `{{commit_date '<format>' tz='<timezone>'}}`
Returns the date when the current git commit is committed, rendered by its
[moment format](https://momentjs.com/docs/#/displaying/format/). It falls back
to the current date if the commit date is not available.
Default `tz` is UTC.
| Expression | Output example |
|-----------------------------------------------------|-----------------------------------------|
| `{{commit_date 'YYYYMMDD'}}` | `20200110` |
| `{{commit_date 'dddd, MMMM Do YYYY, h:mm:ss a'}}` | `Friday, January 10th 2020, 3:25:50 pm` |
| `{{commit_date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}` | `20200110-093000` |
### Major version zero
Major version zero (`0.y.z`) is for initial development and **may** change at
@@ -851,13 +939,13 @@ that you can reuse them further in your workflow using the [`fromJSON` function]
```yaml
-
name: Docker meta
uses: docker/metadata-action@v4
uses: docker/metadata-action@v5
id: meta
with:
images: name/app
-
name: Build and push
uses: docker/build-push-action@v4
uses: docker/build-push-action@v6
with:
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
@@ -867,16 +955,17 @@ that you can reuse them further in your workflow using the [`fromJSON` function]
REVISION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}
```
### Overwrite labels
### Overwrite labels and annotations
If some [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
labels generated are not suitable, you can overwrite them like this:
generated are not suitable as labels/annotations, you can overwrite them like
this:
```yaml
-
name: Docker meta
id: meta
uses: docker/metadata-action@v4
uses: docker/metadata-action@v5
with:
images: name/app
labels: |
@@ -886,6 +975,78 @@ labels generated are not suitable, you can overwrite them like this:
org.opencontainers.image.vendor=MyCompany
```
### Annotations
Since Buildx 0.12, it is possible to set annotations to your image through the
`--annotation` flag.
With the [`build-push-action`](https://github.com/docker/build-push-action/),
you can set the `annotations` input with the value of the `annotations` output
of the `metadata-action`:
```yaml
-
name: Docker meta
uses: docker/metadata-action@v5
with:
images: name/app
-
name: Build and push
uses: docker/build-push-action@v6
with:
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
```
The same can be done with the [`bake-action`](https://github.com/docker/bake-action/):
```yaml
-
name: Docker meta
uses: docker/metadata-action@v5
with:
images: name/app
-
name: Build
uses: docker/bake-action@v6
with:
files: |
./docker-bake.hcl
cwd://${{ steps.meta.outputs.bake-file-tags }}
cwd://${{ steps.meta.outputs.bake-file-annotations }}
targets: build
```
Note that annotations can be attached at many different levels within a manifest.
By default, the generated annotations will be attached to image manifests,
but different registries may expect annotations at different places;
a common practice is to read annotations at _image indexes_ if present,
which are often used by multi-arch builds to index platform-specific images.
If you want to specify level(s) for your annotations, you can use the
[`DOCKER_METADATA_ANNOTATIONS_LEVELS` environment variable](#environment-variables)
with a comma separated list of all levels the annotations should be attached to (defaults to `manifest`).
The following configuration demonstrates the ability to attach annotations to both image manifests and image indexes,
though your registry may only need annotations at the index level. (That is, `index` alone may be enough.)
Please consult the documentation of your registry.
```yaml
-
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@v6
with:
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
```
More information about annotations in the [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md).
## Contributing
Want to contribute? Awesome! You can find information about contributing to