docker · Apr 12, 2022 · Apr 19, 2022 · Apr 20, 2022 · Apr 25, 2022 · Apr 25, 2022
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -146,6 +146,21 @@ jobs:
             prefix=foo-
             suffix=-bar
 
+  images:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v3
+      -
+        name: Docker meta
+        uses: ./
+        with:
+          images: |
+            name=${{ env.DOCKER_IMAGE }}
+            name=ghcr.io/name/app,enable=${{ github.event_name == 'pull_request' }}
+            name=ghcr.io/name/release,enable=${{ startsWith(github.ref, 'refs/tags/') }}
+
   labels:
     runs-on: ubuntu-latest
     steps:
@@ -165,6 +180,27 @@ jobs:
             org.opencontainers.image.description=this is a "good" example
             org.opencontainers.image.vendor=MyCompany
 
+  global-exps:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v3
+      -
+        name: Docker meta
+        uses: ./
+        with:
+          images: |
+            ${{ env.DOCKER_IMAGE }}
+            ghcr.io/name/app
+          tags: |
+            type=sha
+            type=raw,value=gexp-branch-{{branch}}
+            type=raw,value=gexp-date-{{date 'YYYYMMDD'}}
+            type=raw,value=gexp-tag-{{tag}}
+            type=raw,value=gexp-baseref-{{base_ref}}
+            type=raw,value=gexp-defbranch,enable={{is_default_branch}}
+
   json:
     runs-on: ubuntu-latest
     steps:
@@ -205,7 +241,8 @@ jobs:
         id: docker_meta
         uses: ./
         with:
-          images: ${{ env.DOCKER_IMAGE }}
+          images: |
+            ${{ env.DOCKER_IMAGE }}
           tags: |
             type=schedule
             type=ref,event=branch

diff --git a/README.md b/README.md
@@ -19,6 +19,7 @@ ___
 * [Customizing](#customizing)
   * [inputs](#inputs)
   * [outputs](#outputs)
+* [`images` input](#images-input)
 * [`flavor` input](#flavor-input)
 * [`tags` input](#tags-input)
   * [`type=schedule`](#typeschedule)
@@ -32,6 +33,12 @@ ___
 * [Notes](#notes)
   * [Latest tag](#latest-tag)
   * [Global expressions](#global-expressions)
+    * [`{{branch}}`](#branch)
+    * [`{{tag}}`](#tag)
+    * [`{{sha}}`](#sha)
+    * [`{{base_ref}}`](#base_ref)
+    * [`{{is_default_branch}}`](#is_default_branch)
+    * [`{{date '<format>'}}`](#date-format)
   * [Major version zero](#major-version-zero)
   * [JSON output object](#json-output-object)
   * [Overwrite labels](#overwrite-labels)
@@ -119,7 +126,8 @@ jobs:
         id: meta
         uses: docker/metadata-action@v3
         with:
-          images: name/app
+          images: |
+            name/app
           tags: |
             type=ref,event=branch
             type=ref,event=pr
@@ -196,7 +204,8 @@ jobs:
         id: meta
         uses: docker/metadata-action@v3
         with:
-          images: name/app
+          images: |
+            name/app
           tags: |
             type=ref,event=branch
             type=ref,event=pr
@@ -232,7 +241,7 @@ Content of `${{ steps.meta.outputs.bake-file }}` file will look like this with `
         "org.opencontainers.image.source": "https://github.com/octocat/Hello-World",
         "org.opencontainers.image.version": "1.2.3",
         "org.opencontainers.image.created": "2020-01-10T00:30:00.000Z",
-        "org.opencontainers.image.revision": "90dd6032fac8bda1b6c4436a2e65de27961ed071",
+        "org.opencontainers.image.revision": "860c1904a1ce19322e91ac35af1ab07466440c37",
         "org.opencontainers.image.licenses": "MIT"
       },
       "args": {
@@ -258,33 +267,51 @@ Following inputs can be used as `step.with` keys
 >   org.opencontainers.image.vendor=MyCompany
 > ```
 
-> `CSV` type is a comma-delimited string
-> ```yaml
-> images: name/app,ghcr.io/name/app
-> ```
-
-| Name                | Type     | Description                        |
-|---------------------|----------|------------------------------------|
-| `images`            | List/CSV | 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                                              |
+|---------------------|--------|----------------------------------------------------------|
+| `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`)      |
 
 ### outputs
 
 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 |
+| 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 definition file](https://github.com/docker/buildx#file-definition) path |
 
+## `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`)
+
 ## `flavor` input
 
 `flavor` defines a global behavior for [`tags`](#tags-input):
@@ -605,26 +632,28 @@ tags: |
 * [`type=semver,pattern=...`](#typesemver)
 * [`type=match,pattern=...`](#typematch)
 
-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:
+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:
 
 ```yaml
 tags: |
-  type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+  # set latest tag for master branch
+  type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'master') }}
 ```
 
-### Global expressions
+You can also use the [`{{is_default_branch}}` global expression](#is_default_branch)
+to conditionally tag with latest for the default branch:
 
-The following [Handlebars' template](https://handlebarsjs.com/guide/) expressions for `prefix`, `suffix` and `value`
-attributes are available:
+```yaml
+tags: |
+  # set latest tag for default branch
+  type=raw,value=latest,enable={{is_default_branch}}
+```
 
-| Expression               | Output               |
-|--------------------------|----------------------|
-| `{{branch}}`             | `master`             |
-| `{{tag}}`                | `v1.2.3`             |
-| `{{sha}}`                | `90dd603`            |
-| `{{base_ref}}`           | `master`             |
-| `{{date 'YYYYMMDD'}}`    | `20210326`           |
+### Global expressions
+
+The following [Handlebars' template](https://handlebarsjs.com/guide/) expressions
+for `prefix`, `suffix`, `value` and `enable` attributes are available:
 
 ```yaml
 tags: |
@@ -634,6 +663,66 @@ tags: |
   type=raw,value=mytag-{{branch}}-{{sha}}
 ```
 
+#### `{{branch}}`
+
+Returns the branch name that triggered the workflow run. Will be empty if not 
+a branch reference:
+
+| 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`            |                     |
+
+#### `{{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:
+
+| 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). 
+
+#### `{{is_default_branch}}`
+
+Returns `true` if the branch that triggered the workflow run is the default
+one, otherwise `false`.
+
+#### `{{date '<format>'}}`
+
+Returns the current date rendered by its [moment format](https://momentjs.com/docs/#/displaying/format/).
+
+| Expression                                 | Output example                          |
+|--------------------------------------------|-----------------------------------------|
+| `{{date 'YYYYMMDD'}}`                      | `20200110`                              |
+| `{{date 'dddd, MMMM Do YYYY, h:mm:ss a'}}` | `Friday, January 10th 2020, 3:25:50 pm` |
+
 ### Major version zero
 
 Major version zero (`0.y.z`) is for initial development and **may** change at any time. This means the public API

diff --git a/__tests__/fixtures/event_create_branch.env b/__tests__/fixtures/event_create_branch.env
@@ -0,0 +1,30 @@
+GITHUB_ACTION=__crazy-max_ghaction-dump-context
+GITHUB_ACTIONS=true
+GITHUB_ACTION_PATH=/home/runner/work/_actions/crazy-max/ghaction-dump-context/v1
+GITHUB_ACTION_REF=
+GITHUB_ACTION_REPOSITORY=
+GITHUB_ACTOR=crazy-max
+GITHUB_API_URL=https://api.github.com
+GITHUB_BASE_REF=
+GITHUB_ENV=/home/runner/work/_temp/_runner_file_commands/set_env_49ba9b4e-1733-447c-b700-1cea19f95b82
+GITHUB_EVENT_NAME=create
+GITHUB_EVENT_PATH=./__tests__/fixtures/event_create_branch.json
+GITHUB_GRAPHQL_URL=https://api.github.com/graphql
+GITHUB_HEAD_REF=
+GITHUB_JOB=test
+GITHUB_PATH=/home/runner/work/_temp/_runner_file_commands/add_path_49ba9b4e-1733-447c-b700-1cea19f95b82
+GITHUB_REF=refs/heads/dev
+GITHUB_REF_NAME=dev
+GITHUB_REF_PROTECTED=false
+GITHUB_REF_TYPE=branch
+GITHUB_REPOSITORY=docker/test-docker-action
+GITHUB_REPOSITORY_OWNER=docker
+GITHUB_RETENTION_DAYS=90
+GITHUB_RUN_ATTEMPT=1
+GITHUB_RUN_ID=2188731929
+GITHUB_RUN_NUMBER=14
+GITHUB_SERVER_URL=https://github.com
+GITHUB_SHA=5f3331d7f7044c18ca9f12c77d961c4d7cf3276a
+GITHUB_STEP_SUMMARY=/home/runner/work/_temp/_runner_file_commands/step_summary_49ba9b4e-1733-447c-b700-1cea19f95b82
+GITHUB_WORKFLOW=metadata
+GITHUB_WORKSPACE=/home/runner/work/test-docker-action/test-docker-action