2021-05-08 01:41:46 +02:00
[![GitHub release ](https://img.shields.io/github/release/docker/metadata-action.svg?style=flat-square )](https://github.com/docker/metadata-action/releases/latest)
2021-05-10 15:39:06 +02:00
[![GitHub marketplace ](https://img.shields.io/badge/marketplace-docker--metadata--action-blue?logo=github&style=flat-square )](https://github.com/marketplace/actions/docker-metadata-action)
2022-12-19 21:07:37 +01:00
[![CI workflow ](https://img.shields.io/github/actions/workflow/status/docker/metadata-action/ci.yml?branch=master&label=ci&logo=github&style=flat-square )](https://github.com/docker/metadata-action/actions?workflow=ci)
[![Test workflow ](https://img.shields.io/github/actions/workflow/status/docker/metadata-action/test.yml?branch=master&label=test&logo=github&style=flat-square )](https://github.com/docker/metadata-action/actions?workflow=test)
2021-05-08 01:41:46 +02:00
[![Codecov ](https://img.shields.io/codecov/c/github/docker/metadata-action?logo=codecov&style=flat-square )](https://codecov.io/gh/docker/metadata-action)
2021-03-29 13:04:53 +02:00
2020-10-25 02:25:23 +01:00
## About
2022-10-08 02:07:41 +02:00
GitHub Action to extract metadata from Git reference and GitHub events. This action
is particularly useful if used with [Docker Build Push ](https://github.com/docker/build-push-action )
action to tag and label Docker images.
2020-10-25 02:25:23 +01:00
2021-05-08 01:41:46 +02:00
![Screenshot ](.github/metadata-action.png )
2020-10-25 03:21:46 +01:00
2020-10-25 02:25:23 +01:00
___
* [Usage ](#usage )
2020-11-17 23:31:03 +01:00
* [Basic ](#basic )
* [Semver ](#semver )
2020-12-24 04:13:41 +01:00
* [Bake definition ](#bake-definition )
2020-10-25 02:25:23 +01:00
* [Customizing ](#customizing )
* [inputs ](#inputs )
* [outputs ](#outputs )
2022-10-17 11:49:09 +02:00
* [environment variables ](#environment-variables )
2022-12-15 14:46:34 +01:00
* [`context` input ](#context-input )
2022-04-27 16:58:50 +02:00
* [`images` input ](#images-input )
2021-03-29 13:04:53 +02:00
* [`flavor` input ](#flavor-input )
* [`tags` input ](#tags-input )
* [`type=schedule` ](#typeschedule )
* [`type=semver` ](#typesemver )
2021-07-06 13:56:48 +02:00
* [`type=pep440` ](#typepep440 )
2021-03-29 13:04:53 +02:00
* [`type=match` ](#typematch )
* [`type=edge` ](#typeedge )
* [`type=ref` ](#typeref )
* [`type=raw` ](#typeraw )
* [`type=sha` ](#typesha )
2020-10-25 15:13:43 +01:00
* [Notes ](#notes )
2022-05-04 15:02:47 +02:00
* [Image name and tag sanitization ](#image-name-and-tag-sanitization )
2020-10-28 18:25:31 +01:00
* [Latest tag ](#latest-tag )
2022-10-08 01:10:48 +02:00
* [`priority` attribute ](#priority-attribute )
2021-05-07 21:53:30 +02:00
* [Global expressions ](#global-expressions )
2022-04-25 13:41:39 +02:00
* [`{{branch}}` ](#branch )
* [`{{tag}}` ](#tag )
* [`{{sha}}` ](#sha )
* [`{{base_ref}}` ](#base_ref )
* [`{{is_default_branch}}` ](#is_default_branch )
2023-01-11 16:17:34 +01:00
* [`{{date '<format>' tz='<timezone>'}}` ](#date-format-tztimezone )
2021-05-08 00:01:13 +02:00
* [Major version zero ](#major-version-zero )
2021-05-22 21:23:06 +02:00
* [JSON output object ](#json-output-object )
2020-10-27 14:13:48 +01:00
* [Overwrite labels ](#overwrite-labels )
2022-10-08 02:07:41 +02:00
* [Contributing ](#contributing )
2020-10-25 02:25:23 +01:00
2020-11-17 23:31:03 +01:00
## Usage
### Basic
2020-10-25 15:17:39 +01:00
2020-11-17 23:31:03 +01:00
```yaml
name: ci
on:
2022-10-08 00:48:17 +02:00
workflow_dispatch:
2020-11-17 23:31:03 +01:00
push:
branches:
2021-03-29 13:04:53 +02:00
- 'master'
2020-11-17 23:31:03 +01:00
tags:
- 'v*'
pull_request:
2021-03-29 13:04:53 +02:00
branches:
- 'master'
2020-11-17 23:31:03 +01:00
jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
2023-09-12 10:25:45 +02:00
uses: actions/checkout@v4
2020-11-17 23:31:03 +01:00
-
name: Docker meta
2021-03-29 13:04:53 +02:00
id: meta
2023-09-12 10:25:45 +02:00
uses: docker/metadata-action@v5
2020-11-17 23:31:03 +01:00
with:
images: name/app
-
name: Login to DockerHub
if: github.event_name != 'pull_request'
2023-09-12 10:25:45 +02:00
uses: docker/login-action@v3
2020-11-17 23:31:03 +01:00
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
2023-09-12 10:25:45 +02:00
uses: docker/build-push-action@v5
2020-11-17 23:31:03 +01:00
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
2021-03-29 13:04:53 +02:00
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
2020-11-17 23:31:03 +01:00
```
2022-10-08 00:48:17 +02:00
| Event | Ref | Docker Tags |
|---------------------|-------------------------------|----------------------------|
| `pull_request` | `refs/pull/2/merge` | `pr-2` |
| `push` | `refs/heads/master` | `master` |
| `push` | `refs/heads/releases/v1` | `releases-v1` |
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3` , `latest` |
| `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67` , `latest` |
| `workflow_dispatch` | `refs/heads/master` | `master` |
2020-11-17 23:31:03 +01:00
2021-03-29 13:04:53 +02:00
### Semver
2020-11-17 23:31:03 +01:00
```yaml
name: ci
on:
push:
branches:
2021-03-29 13:04:53 +02:00
- 'master'
2020-11-17 23:31:03 +01:00
tags:
- 'v*'
pull_request:
2021-03-29 13:04:53 +02:00
branches:
- 'master'
2020-11-17 23:31:03 +01:00
jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
2023-09-12 10:25:45 +02:00
uses: actions/checkout@v4
2020-11-17 23:31:03 +01:00
-
name: Docker meta
2021-03-29 13:04:53 +02:00
id: meta
2023-09-12 10:25:45 +02:00
uses: docker/metadata-action@v5
2020-11-17 23:31:03 +01:00
with:
2022-04-28 09:08:21 +02:00
images: |
name/app
2021-03-29 13:04:53 +02:00
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
2020-11-17 23:31:03 +01:00
-
name: Login to DockerHub
if: github.event_name != 'pull_request'
2023-09-12 10:25:45 +02:00
uses: docker/login-action@v3
2020-11-17 23:31:03 +01:00
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
-
name: Build and push
2023-09-12 10:25:45 +02:00
uses: docker/build-push-action@v5
2020-11-17 23:31:03 +01:00
with:
context: .
push: ${{ github.event_name != 'pull_request' }}
2021-03-29 13:04:53 +02:00
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
2020-11-17 23:31:03 +01:00
```
2021-03-29 13:04:53 +02:00
| Event | Ref | Docker Tags |
|-----------------|-------------------------------|-------------------------------------|
| `pull_request` | `refs/pull/2/merge` | `pr-2` |
| `push` | `refs/heads/master` | `master` |
| `push` | `refs/heads/releases/v1` | `releases-v1` |
| `push tag` | `refs/tags/v1.2.3` | `1.2.3` , `1.2` , `latest` |
| `push tag` | `refs/tags/v2.0.8-beta.67` | `2.0.8-beta.67` |
2020-12-24 04:13:41 +01:00
### Bake definition
2020-11-17 23:31:03 +01:00
2020-12-24 04:13:41 +01:00
This action also handles a bake definition file that can be used with the
2022-10-08 02:07:41 +02:00
[Docker Bake action ](https://github.com/docker/bake-action ). You just have to
declare an empty target named `docker-metadata-action` and inherit from it.
2020-12-24 04:13:41 +01:00
```hcl
// docker-bake.hcl
2021-05-10 15:54:35 +02:00
target "docker-metadata-action" {}
2020-12-24 04:13:41 +01:00
target "build" {
2021-05-10 15:54:35 +02:00
inherits = ["docker-metadata-action"]
2020-12-24 04:13:41 +01:00
context = "./"
dockerfile = "Dockerfile"
2021-06-23 12:04:02 +02:00
platforms = [
"linux/amd64",
"linux/arm/v6",
"linux/arm/v7",
"linux/arm64",
"linux/386"
]
2020-12-24 04:13:41 +01:00
}
```
2020-10-25 02:25:23 +01:00
```yaml
name: ci
on:
push:
branches:
2021-03-29 13:04:53 +02:00
- 'master'
2020-10-25 02:25:23 +01:00
tags:
2020-11-17 23:31:03 +01:00
- 'v*'
2020-10-25 02:25:23 +01:00
jobs:
docker:
runs-on: ubuntu-latest
steps:
-
name: Checkout
2023-09-12 10:25:45 +02:00
uses: actions/checkout@v4
2020-10-25 02:25:23 +01:00
-
name: Docker meta
2021-03-29 13:04:53 +02:00
id: meta
2023-09-12 10:25:45 +02:00
uses: docker/metadata-action@v5
2020-10-25 02:25:23 +01:00
with:
2022-04-28 09:08:21 +02:00
images: |
name/app
2021-03-29 13:04:53 +02:00
tags: |
type=ref,event=branch
type=ref,event=pr
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=sha
2020-10-25 02:25:23 +01:00
-
2020-12-24 04:13:41 +01:00
name: Build
2023-09-12 10:25:45 +02:00
uses: docker/bake-action@v3
2020-10-25 02:25:23 +01:00
with:
2020-12-24 04:13:41 +01:00
files: |
./docker-bake.hcl
2021-03-29 13:04:53 +02:00
${{ steps.meta.outputs.bake-file }}
targets: build
2020-10-25 02:25:23 +01:00
```
2022-10-08 02:07:41 +02:00
Content of `${{ steps.meta.outputs.bake-file }}` file will look like this with
`refs/tags/v1.2.3` ref:
2020-12-24 14:06:20 +01:00
```json
{
"target": {
2021-05-10 15:54:35 +02:00
"docker-metadata-action": {
2020-12-24 14:06:20 +01:00
"tags": [
2021-03-29 13:04:53 +02:00
"name/app:1.2.3",
"name/app:1.2",
"name/app:sha-90dd603",
2020-12-24 14:06:20 +01:00
"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",
2021-03-29 13:04:53 +02:00
"org.opencontainers.image.version": "1.2.3",
2020-12-24 14:06:20 +01:00
"org.opencontainers.image.created": "2020-01-10T00:30:00.000Z",
2022-04-25 13:41:39 +02:00
"org.opencontainers.image.revision": "860c1904a1ce19322e91ac35af1ab07466440c37",
2020-12-24 14:06:20 +01:00
"org.opencontainers.image.licenses": "MIT"
2020-12-24 16:45:28 +01:00
},
"args": {
"DOCKER_META_IMAGES": "name/app",
2021-03-29 13:04:53 +02:00
"DOCKER_META_VERSION": "1.2.3"
2020-12-24 14:06:20 +01:00
}
}
}
}
```
2020-10-25 02:25:23 +01:00
## Customizing
### inputs
2023-09-12 10:25:45 +02:00
The following inputs can be used as `step.with` keys:
2020-10-25 02:25:23 +01:00
2020-12-23 22:09:38 +01:00
> `List` type is a newline-delimited string
> ```yaml
2021-03-31 10:01:20 +02:00
> labels: |
2020-12-23 22:09:38 +01:00
> org.opencontainers.image.title=MyCustomTitle
> org.opencontainers.image.description=Another description
> org.opencontainers.image.vendor=MyCompany
> ```
2022-12-15 14:46:34 +01:00
| 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` ) |
2020-10-25 02:25:23 +01:00
### outputs
2023-09-12 10:25:45 +02:00
The following outputs are available:
2020-10-25 02:25:23 +01:00
2023-09-12 10:25:45 +02:00
| 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/bake/reference/ ) path |
2020-10-25 02:25:23 +01:00
2023-01-13 10:45:14 +01:00
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 ](https://github.com/docker/build-push-action/ ):
```yaml
2023-09-12 10:25:45 +02:00
- uses: docker/build-push-action@v5
2023-01-13 10:45:14 +01:00
with:
build-args: |
DOCKER_METADATA_OUTPUT_JSON
```
2022-10-17 11:49:09 +02:00
### 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 |
2022-12-15 14:46:34 +01:00
## `context` input
`context` defines where to get context metadata:
```yaml
# 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` .
2022-04-27 16:58:50 +02:00
## `images` input
`images` defines a list of Docker images to use as base name for [`tags` ](#tags-input ):
```yaml
images: |
name/foo
ghcr.io/name/bar
# or
name=name/foo
name=ghcr.io/name/bar
```
Extended attributes and default values:
```yaml
images: |
name=,enable=true
```
* `name=<string>` image base name
* `enable=<true|false>` enable this entry (default `true` )
2021-03-29 13:04:53 +02:00
## `flavor` input
2020-10-25 15:13:43 +01:00
2021-03-29 13:04:53 +02:00
`flavor` defines a global behavior for [`tags` ](#tags-input ):
2020-10-28 18:25:31 +01:00
2021-03-29 13:04:53 +02:00
```yaml
flavor: |
latest=auto
prefix=
suffix=
```
2020-11-20 23:12:14 +01:00
2021-03-29 13:04:53 +02:00
* `latest=<auto|true|false>` : Handle [latest tag ](#latest-tag ) (default `auto` )
2022-10-08 02:07:41 +02:00
* `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`
2020-11-20 23:12:14 +01:00
2021-03-29 13:04:53 +02:00
## `tags` input
2020-11-18 17:56:34 +01:00
2022-10-08 02:07:41 +02:00
`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
2021-03-29 13:04:53 +02:00
(only string format is handled in the input fields). Here is an example:
2020-10-25 15:13:43 +01:00
2021-03-29 13:04:53 +02:00
```yaml
tags: |
type=schedule
type=semver,pattern={{version}}
type=semver,pattern={{major}}.{{minor}}
type=semver,pattern={{major}}
2021-10-03 17:30:52 +02:00
type=ref,event=branch
type=ref,event=pr
2021-03-29 13:04:53 +02:00
type=sha
```
Each entry is defined by a `type` , which are:
* [`type=schedule` ](#typeschedule )
* [`type=semver` ](#typesemver )
2021-10-03 17:30:52 +02:00
* [`type=pep440` ](#typepep440 )
2021-03-29 13:04:53 +02:00
* [`type=match` ](#typematch )
* [`type=edge` ](#typeedge )
* [`type=ref` ](#typeref )
* [`type=raw` ](#typeraw )
* [`type=sha` ](#typesha )
And global attributes:
* `enable=<true|false>` enable this entry (default `true` )
2022-10-08 01:10:48 +02:00
* `priority=<number>` set tag [priority ](#priority-attribute ) order
2021-03-29 13:04:53 +02:00
* `prefix=<string>` add prefix
* `suffix=<string>` add suffix
Default entries if `tags` input is empty:
```yaml
tags: |
type=schedule
type=ref,event=branch
type=ref,event=tag
type=ref,event=pr
```
### `type=schedule`
```yaml
tags: |
# minimal
type=schedule
# default
type=schedule,pattern=nightly
# handlebars
type=schedule,pattern={{date 'YYYYMMDD'}}
2022-12-29 01:01:17 +01:00
# handlebars with timezone
type=schedule,pattern={{date 'YYYYMMDD-hhmmss' tz='Asia/Tokyo'}}
2021-03-29 13:04:53 +02:00
```
2022-10-08 02:07:41 +02:00
Will be used on [schedule event ](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule ).
`pattern` is a specially crafted attribute to support [Handlebars' template ](https://handlebarsjs.com/guide/ )
with the following expressions:
2021-03-29 13:04:53 +02:00
2023-01-11 16:17:34 +01:00
* `date 'format' tz='Timezone'` ; render date by its [moment format ](https://momentjs.com/docs/#/displaying/format/ ).
Default `tz` is UTC.
2021-03-29 13:04:53 +02:00
2023-01-11 16:17:34 +01:00
| Pattern | Output |
|----------------------------------------------|-------------------|
| `nightly` | `nightly` |
| `{{date 'YYYYMMDD'}}` | `20200110` |
| `{{date 'YYYYMMDD-HHmmss' tz='Asia/Tokyo'}}` | `20200110-093000` |
2021-03-29 13:04:53 +02:00
Extended attributes and default values:
```yaml
tags: |
type=schedule,enable=true,priority=1000,prefix=,suffix=,pattern=nightly
```
### `type=semver`
```yaml
tags: |
# minimal
type=semver,pattern={{version}}
# use custom value instead of git tag
type=semver,pattern={{version}},value=v1.0.0
```
2022-10-08 02:07:41 +02:00
Will be used on a [push tag event ](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push )
and requires a valid [semver ](https://semver.org/ ) Git tag, but you can also
use a custom value through `value` attribute.
`pattern` attribute supports [Handlebars template ](https://handlebarsjs.com/guide/ )
with the following expressions:
2021-03-29 13:04:53 +02:00
2021-07-06 13:56:48 +02:00
* `raw` ; the actual tag
2021-03-29 13:04:53 +02:00
* `version` ; shorthand for `{{major}}.{{minor}}.{{patch}}` (can include pre-release)
* `major` ; major version identifier
* `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` |
2021-12-06 17:15:06 +01:00
| `v2.0.8-beta.67` | `{{raw}}` | `v2.0.8-beta.67` |
2021-03-29 13:04:53 +02:00
| `v2.0.8-beta.67` | `{{version}}` | `2.0.8-beta.67` |
| `v2.0.8-beta.67` | `{{major}}.{{minor}}` | `2.0.8-beta.67` * |
2022-10-08 02:07:41 +02:00
> *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.
2021-03-29 13:04:53 +02:00
Extended attributes and default values:
2020-10-25 15:13:43 +01:00
2021-03-29 13:04:53 +02:00
```yaml
tags: |
type=semver,enable=true,priority=900,prefix=,suffix=,pattern=,value=
```
2021-07-06 13:56:48 +02:00
### `type=pep440`
```yaml
tags: |
# minimal
type=pep440,pattern={{version}}
# use custom value instead of git tag
type=pep440,pattern={{version}},value=1.0.0
```
2022-10-08 02:07:41 +02:00
Will be used on a [push tag event ](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push )
and requires a Git tag that conforms to [PEP 440 ](https://www.python.org/dev/peps/pep-0440/ ),
but you can also use a custom value through `value` attribute.
`pattern` attribute supports [Handlebars template ](https://handlebarsjs.com/guide/ )
with the following expressions:
2021-07-06 13:56:48 +02:00
* `raw` ; the actual tag
* `version` ; cleaned version
* `major` ; major version identifier
* `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` |
2021-12-06 17:15:06 +01:00
| `v1.2.3rc2` | `{{raw}}` | `v1.2.3rc2` |
2021-07-06 13:56:48 +02:00
| `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` * |
2022-10-08 02:07:41 +02:00
> *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.
2021-07-06 13:56:48 +02:00
Extended attributes and default values:
```yaml
tags: |
type=pep440,enable=true,priority=900,prefix=,suffix=,pattern=,value=
```
2021-03-29 13:04:53 +02:00
### `type=match`
```yaml
tags: |
# minimal
2021-04-03 18:15:27 +02:00
type=match,pattern=\d.\d.\d
2021-03-29 13:04:53 +02:00
# 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
```
2022-10-08 02:07:41 +02:00
Can create a regular expression for matching Git tag with a pattern and
capturing group. Will be used on a [push tag event ](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push )
but, you can also use a custom value through `value` attribute.
2021-03-29 13:04:53 +02:00
2022-05-04 15:02:20 +02:00
| Git tag | Pattern | Group | Output |
|-------------------------|------------------|---------|------------------------|
| `v1.2.3` | `\d.\d.\d` | `0` | `1.2.3` |
| `v2.0.8-beta.67` | `v(.*)` | `1` | `2.0.8-beta.67` |
| `v2.0.8-beta.67` | `v(\d.\d)` | `1` | `2.0` |
| `20200110-RC2` | `\d+` | `0` | `20200110` |
| `p1/v1.2.3` | `p1/v(\d.\d.\d)` | `1` | `1.2.3` |
2021-03-29 13:04:53 +02:00
Extended attributes and default values:
```yaml
tags: |
2021-04-03 18:18:32 +02:00
type=match,enable=true,priority=800,prefix=,suffix=,pattern=,group=0,value=
2021-03-29 13:04:53 +02:00
```
### `type=edge`
```yaml
tags: |
# minimal
type=edge
# define default branch
type=edge,branch=main
```
2022-10-08 02:07:41 +02:00
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 ](https://hub.docker.com/_/alpine ).
2021-03-29 13:04:53 +02:00
Extended attributes and default values:
```yaml
tags: |
type=edge,enable=true,priority=700,prefix=,suffix=,branch=$repo.default_branch
```
### `type=ref`
```yaml
tags: |
2021-04-05 21:19:05 +02:00
# branch event
2021-03-29 13:04:53 +02:00
type=ref,event=branch
2021-04-05 21:19:05 +02:00
# tag event
2021-03-29 13:04:53 +02:00
type=ref,event=tag
2021-04-05 21:19:05 +02:00
# pull request event
2021-03-29 13:04:53 +02:00
type=ref,event=pr
```
This type handles Git ref (or reference) for the following events:
2022-10-08 02:07:41 +02:00
2021-03-29 13:04:53 +02:00
* `branch` ; eg. `refs/heads/master`
* `tag` ; eg. `refs/tags/v1.0.0`
* `pr` ; eg. `refs/pull/318/merge`
2022-10-08 00:48:17 +02:00
| Event | Ref | Output |
|---------------------|-------------------------------|------------------|
| `pull_request` | `refs/pull/2/merge` | `pr-2` |
| `push` | `refs/heads/master` | `master` |
| `push` | `refs/heads/my/branch` | `my-branch` |
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3` |
| `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67` |
| `workflow_dispatch` | `refs/heads/master` | `master` |
2021-03-29 13:04:53 +02:00
Extended attributes and default values:
```yaml
tags: |
2021-04-05 21:19:05 +02:00
# branch event
2021-07-12 17:08:07 +02:00
type=ref,enable=true,priority=600,prefix=,suffix=,event=branch
2021-04-05 21:19:05 +02:00
# tag event
2021-07-12 17:08:07 +02:00
type=ref,enable=true,priority=600,prefix=,suffix=,event=tag
2021-04-05 21:19:05 +02:00
# pull request event
2021-07-12 17:08:07 +02:00
type=ref,enable=true,priority=600,prefix=pr-,suffix=,event=pr
2021-03-29 13:04:53 +02:00
```
### `type=raw`
```yaml
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:
```yaml
tags: |
type=raw,enable=true,priority=200,prefix=,suffix=,value=
```
### `type=sha`
```yaml
tags: |
2021-05-13 21:46:07 +02:00
# minimal (short sha)
2021-05-11 20:14:23 +02:00
type=sha
# full length sha
type=sha,format=long
```
Output Git short commit (or long if specified) as Docker tag like `sha-ad132f5` .
2021-03-29 13:04:53 +02:00
Extended attributes and default values:
```yaml
tags: |
2021-05-11 20:14:23 +02:00
type=sha,enable=true,priority=100,prefix=sha-,suffix=,format=short
2021-03-29 13:04:53 +02:00
```
## Notes
2022-05-04 15:02:47 +02:00
### Image name and tag sanitization
2022-10-08 02:07:41 +02:00
In order to comply with [the specification ](https://docs.docker.com/engine/reference/commandline/tag/#description ),
2022-05-04 15:02:47 +02:00
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
2021-03-29 13:04:53 +02:00
### Latest tag
2020-10-25 15:13:43 +01:00
2022-10-08 02:07:41 +02:00
`latest` tag is handled through the [`flavor` input ](#flavor-input ). It will be
generated by default (`auto` mode) for:
2021-03-29 13:04:53 +02:00
* [`type=ref,event=tag` ](#typeref )
* [`type=semver,pattern=...` ](#typesemver )
* [`type=match,pattern=...` ](#typematch )
2020-10-25 15:13:43 +01:00
2022-04-25 13:41:39 +02:00
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:
2022-01-09 13:46:39 +01:00
```yaml
tags: |
2022-04-25 13:41:39 +02:00
# set latest tag for master branch
type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'master') }}
2022-01-09 13:46:39 +01:00
```
2022-04-25 13:41:39 +02:00
You can also use the [`{{is_default_branch}}` global expression ](#is_default_branch )
to conditionally tag with latest for the default branch:
2021-05-07 21:53:30 +02:00
2022-04-25 13:41:39 +02:00
```yaml
tags: |
# set latest tag for default branch
type=raw,value=latest,enable={{is_default_branch}}
```
2021-05-07 21:53:30 +02:00
2022-10-08 01:10:48 +02:00
### `priority` attribute
`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 ](#outputs ).
Each tags `type` attribute has a default priority:
| Attribute | Default priority |
|------------|------------------|
| `schedule` | `1000` |
| `semver` | `900` |
| `pep440` | `900` |
| `match` | `800` |
| `edge` | `700` |
| `ref` | `600` |
| `raw` | `200` |
| `sha` | `100` |
2022-04-25 13:41:39 +02:00
### Global expressions
The following [Handlebars' template ](https://handlebarsjs.com/guide/ ) expressions
for `prefix` , `suffix` , `value` and `enable` attributes are available:
2021-05-07 21:53:30 +02:00
```yaml
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}}
```
2022-04-25 13:41:39 +02:00
#### `{{branch}}`
Returns the branch name that triggered the workflow run. Will be empty if not
a branch reference:
2022-10-08 02:07:41 +02:00
| Event | Ref | Output |
|----------------|------------------------|-------------|
| `pull_request` | `refs/pull/2/merge` | |
| `push` | `refs/heads/master` | `master` |
| `push` | `refs/heads/my/branch` | `my-branch` |
| `push tag` | `refs/tags/v1.2.3` | |
2022-04-25 13:41:39 +02:00
#### `{{tag}}`
Returns the tag name that triggered the workflow run. Will be empty if not a
tag reference:
| Event | Ref | Output |
|-----------------|-------------------------------|--------------------|
| `pull_request` | `refs/pull/2/merge` | |
| `push` | `refs/heads/master` | |
| `push` | `refs/heads/my/branch` | |
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3` |
#### `{{sha}}`
Returns the short commit SHA that triggered the workflow run (e.g., `90dd603` ).
#### `{{base_ref}}`
Returns the base ref or target branch of the pull request that triggered the
workflow run. Will be empty for a branch reference:
2022-04-26 14:47:46 +02:00
| Event | Ref | Output |
|----------------|-------------------------------|--------------------|
| `pull_request` | `refs/pull/2/merge` | `master` |
| `push` | `refs/heads/master` | |
| `push` | `refs/heads/my/branch` | |
| `push tag` * | `refs/tags/v1.2.3` | `master` |
> *`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).
> We keep it for backward compatibility, but it's **not recommended relying on it**.
> More context in [#192](https://github.com/docker/metadata-action/pull/192#discussion_r854673012).
2022-04-25 13:41:39 +02:00
#### `{{is_default_branch}}`
Returns `true` if the branch that triggered the workflow run is the default
one, otherwise `false` .
2022-12-29 01:01:17 +01:00
#### `{{date '<format>' tz='<timezone>'}}`
2022-04-25 13:41:39 +02:00
2023-01-11 16:17:34 +01:00
Returns the current date rendered by its [moment format ](https://momentjs.com/docs/#/displaying/format/ ).
Default `tz` is UTC.
2022-04-25 13:41:39 +02:00
2023-01-11 16:17:34 +01:00
| Expression | Output example |
|----------------------------------------------|-----------------------------------------|
| `{{date 'YYYYMMDD'}}` | `20200110` |
| `{{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` |
2022-04-25 13:41:39 +02:00
2021-05-08 00:01:13 +02:00
### Major version zero
2022-10-08 02:07:41 +02:00
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 ](https://semver.org/#spec-item-4 ).
2021-05-08 00:01:13 +02:00
2022-10-08 02:07:41 +02:00
In this case, Docker tag `0` **should not** be generated if you're using [`type=semver` ](#typesemver )
with `{{major}}` pattern. You can manage this behavior like this:
2021-05-08 00:01:13 +02:00
```yaml
# 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.') }}
```
2021-05-22 21:23:06 +02:00
### JSON output object
2022-10-08 02:07:41 +02:00
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 ](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson ):
2021-05-22 21:23:06 +02:00
```yaml
-
name: Docker meta
2023-09-12 10:25:45 +02:00
uses: docker/metadata-action@v5
2021-05-22 21:23:06 +02:00
id: meta
with:
images: name/app
-
name: Build and push
2023-09-12 10:25:45 +02:00
uses: docker/build-push-action@v5
2021-05-22 21:23:06 +02:00
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'] }}
```
2020-10-27 14:13:48 +01:00
### Overwrite labels
2022-03-07 07:37:59 +01:00
If some [OCI Image Format Specification ](https://github.com/opencontainers/image-spec/blob/master/annotations.md )
2020-10-27 14:13:48 +01:00
labels generated are not suitable, you can overwrite them like this:
```yaml
-
2020-12-23 22:09:38 +01:00
name: Docker meta
2021-05-22 21:23:06 +02:00
id: meta
2023-09-12 10:25:45 +02:00
uses: docker/metadata-action@v5
2020-10-27 14:13:48 +01:00
with:
2020-12-23 22:09:38 +01:00
images: name/app
2021-03-29 13:04:53 +02:00
labels: |
2020-12-23 22:09:38 +01:00
maintainer=CrazyMax
2020-10-27 14:13:48 +01:00
org.opencontainers.image.title=MyCustomTitle
org.opencontainers.image.description=Another description
org.opencontainers.image.vendor=MyCompany
```
2022-10-08 02:07:41 +02:00
## Contributing
2020-10-25 02:25:23 +01:00
2022-10-08 02:07:41 +02:00
Want to contribute? Awesome! You can find information about contributing to
this project in the [CONTRIBUTING.md ](/.github/CONTRIBUTING.md )