actions/metadata-action
1
0
Fork 0
mirror of https://github.com/docker/metadata-action.git synced 2024-11-22 20:15:41 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #235 from crazy-max/update-docs

Browse Source 
docs: update
This commit is contained in:
CrazyMax 2022-10-08 02:32:20 +02:00 committed by GitHub
commit 210d783f42
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 116 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
README.md
View File

@ -5,8 +5,9 @@
## About ## About
GitHub Action to extract metadata from Git reference and GitHub events. GitHub Action to extract metadata from Git reference and GitHub events. This action
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. is particularly useful if used with [Docker Build Push](https://github.com/docker/build-push-action)
action to tag and label Docker images.
![Screenshot](.github/metadata-action.png) ![Screenshot](.github/metadata-action.png)
@ -33,6 +34,7 @@ ___
* [Notes](#notes) * [Notes](#notes)
* [Image name and tag sanitization](#image-name-and-tag-sanitization) * [Image name and tag sanitization](#image-name-and-tag-sanitization)
* [Latest tag](#latest-tag) * [Latest tag](#latest-tag)
* [`priority` attribute](#priority-attribute)
* [Global expressions](#global-expressions) * [Global expressions](#global-expressions)
* [`{{branch}}`](#branch) * [`{{branch}}`](#branch)
* [`{{tag}}`](#tag) * [`{{tag}}`](#tag)
@ -43,7 +45,7 @@ ___
* [Major version zero](#major-version-zero) * [Major version zero](#major-version-zero)
* [JSON output object](#json-output-object) * [JSON output object](#json-output-object)
* [Overwrite labels](#overwrite-labels) * [Overwrite labels](#overwrite-labels)
* [Keep up-to-date with GitHub Dependabot](#keep-up-to-date-with-github-dependabot) * [Contributing](#contributing)
## Usage ## Usage
@ -53,6 +55,7 @@ ___
name: ci name: ci
on: on:
workflow_dispatch:
push: push:
branches: branches:
- 'master' - 'master'
@ -92,13 +95,14 @@ jobs:
labels: ${{ steps.meta.outputs.labels }} labels: ${{ steps.meta.outputs.labels }}
``` ```
| Event | Ref | Docker Tags | | Event | Ref | Docker Tags |
|-----------------|-------------------------------|-------------------------------------| |---------------------|-------------------------------|----------------------------|
| `pull_request` | `refs/pull/2/merge` | `pr-2` | | `pull_request` | `refs/pull/2/merge` | `pr-2` |
| `push` | `refs/heads/master` | `master` | | `push` | `refs/heads/master` | `master` |
| `push` | `refs/heads/releases/v1` | `releases-v1` | | `push` | `refs/heads/releases/v1` | `releases-v1` |
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3`, `latest` | | `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` | | `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67`, `latest` |
| `workflow_dispatch` | `refs/heads/master` | `master` |
### Semver ### Semver
@ -162,8 +166,8 @@ jobs:
### Bake definition ### Bake definition
This action also handles a bake definition file that can be used with the This action also handles a bake definition file that can be used with the
[Docker Bake action](https://github.com/docker/bake-action). You just have to declare an empty target named [Docker Bake action](https://github.com/docker/bake-action). You just have to
`docker-metadata-action` and inherit from it. declare an empty target named `docker-metadata-action` and inherit from it.
```hcl ```hcl
// docker-bake.hcl // docker-bake.hcl
@ -223,7 +227,8 @@ jobs:
targets: build 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 will look like this with
`refs/tags/v1.2.3` ref:
```json ```json
{ {
@ -282,13 +287,13 @@ Following inputs can be used as `step.with` keys
Following outputs are available Following outputs are available
| Name | Type | Description | | Name | Type | Description |
|---------------|---------|-------------------------------------------------------------------------------| |---------------|---------|--------------------------------------------------------------------------------------------|
| `version` | String | Docker image version | | `version` | String | Docker image version |
| `tags` | String | Docker tags | | `tags` | String | Docker tags |
| `labels` | String | Docker labels | | `labels` | String | Docker labels |
| `json` | String | JSON output of tags and labels | | `json` | String | JSON output of tags and labels |
| `bake-file` | File | [Bake definition file](https://github.com/docker/buildx#file-definition) path | | `bake-file` | File | [Bake file definition](https://docs.docker.com/build/customize/bake/file-definition/) path |
## `images` input ## `images` input
@ -325,13 +330,16 @@ flavor: |
``` ```
* `latest=<auto|true|false>`: Handle [latest tag](#latest-tag) (default `auto`) * `latest=<auto|true|false>`: Handle [latest tag](#latest-tag) (default `auto`)
* `prefix=<string>,onlatest=<true|false>`: A global prefix for each generated tag and optionally for `latest` * `prefix=<string>,onlatest=<true|false>`: A global prefix for each generated
* `suffix=<string>,onlatest=<true|false>`: A global suffix for each generated tag and optionally for `latest` tag and optionally for `latest`
* `suffix=<string>,onlatest=<true|false>`: A global suffix for each generated
tag and optionally for `latest`
## `tags` input ## `tags` input
`tags` is the core input of this action as everything related to it will reflect the output metadata. This one is in `tags` is the core input of this action as everything related to it will
the form of a key-value pair list in CSV format to remove limitations intrinsically linked to GitHub Actions 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
(only string format is handled in the input fields). Here is an example: (only string format is handled in the input fields). Here is an example:
```yaml ```yaml
@ -359,7 +367,7 @@ Each entry is defined by a `type`, which are:
And global attributes: And global attributes:
* `enable=<true|false>` enable this entry (default `true`) * `enable=<true|false>` enable this entry (default `true`)
* `priority=<number>` priority to manage the order of tags * `priority=<number>` set tag [priority](#priority-attribute) order
* `prefix=<string>` add prefix * `prefix=<string>` add prefix
* `suffix=<string>` add suffix * `suffix=<string>` add suffix
@ -385,10 +393,11 @@ tags: |
type=schedule,pattern={{date 'YYYYMMDD'}} type=schedule,pattern={{date 'YYYYMMDD'}}
``` ```
Will be used on [schedule event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule). 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:
`pattern` is a specially crafted attribute to support [Handlebars' template](https://handlebarsjs.com/guide/) with
the following expressions:
* `date 'format'` ; render date by its [moment format](https://momentjs.com/docs/#/displaying/format/) * `date 'format'` ; render date by its [moment format](https://momentjs.com/docs/#/displaying/format/)
| Pattern | Output | | Pattern | Output |
@ -413,11 +422,13 @@ tags: |
type=semver,pattern={{version}},value=v1.0.0 type=semver,pattern={{version}},value=v1.0.0
``` ```
Will be used on a [push tag event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push) 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` and requires a valid [semver](https://semver.org/) Git tag, but you can also
attribute. use a custom value through `value` attribute.
`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/)
with the following expressions:
`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/) with the following expressions:
* `raw` ; the actual tag * `raw` ; the actual tag
* `version` ; shorthand for `{{major}}.{{minor}}.{{patch}}` (can include pre-release) * `version` ; shorthand for `{{major}}.{{minor}}.{{patch}}` (can include pre-release)
* `major` ; major version identifier * `major` ; major version identifier
@ -436,9 +447,10 @@ attribute.
| `v2.0.8-beta.67` | `{{version}}` | `2.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`* | | `v2.0.8-beta.67` | `{{major}}.{{minor}}` | `2.0.8-beta.67`* |
> *Pre-release (rc, beta, alpha) will only extend `{{version}}` (or `{{raw}}` if specified) as tag > *Pre-release (rc, beta, alpha) will only extend `{{version}}` (or `{{raw}}`
> because they are updated frequently, and contain many breaking changes that are (by the author's design) > if specified) as tag because they are updated frequently, and contain many
> not yet fit for public consumption. > breaking changes that are (by the author's design) not yet fit for public
> consumption.
Extended attributes and default values: Extended attributes and default values:
@ -457,11 +469,13 @@ tags: |
type=pep440,pattern={{version}},value=1.0.0 type=pep440,pattern={{version}},value=1.0.0
``` ```
Will be used on a [push tag event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push) 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 and requires a Git tag that conforms to [PEP 440](https://www.python.org/dev/peps/pep-0440/),
custom value through `value` attribute. but you can also use a custom value through `value` attribute.
`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/)
with the following expressions:
`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/) with the following expressions:
* `raw` ; the actual tag * `raw` ; the actual tag
* `version` ; cleaned version * `version` ; cleaned version
* `major` ; major version identifier * `major` ; major version identifier
@ -482,9 +496,10 @@ custom value through `value` attribute.
| `1.2.3beta2` | `{{major}}.{{minor}}` | `1.2.3b2`* | | `1.2.3beta2` | `{{major}}.{{minor}}` | `1.2.3b2`* |
| `1.0dev4` | `{{major}}.{{minor}}` | `1.0.dev4`* | | `1.0dev4` | `{{major}}.{{minor}}` | `1.0.dev4`* |
> *dev/pre/post release will only extend `{{version}}` (or `{{raw}}` if specified) as tag > *dev/pre/post release will only extend `{{version}}` (or `{{raw}}` if
> because they are updated frequently, and contain many breaking changes that are (by the author's design) > specified) as tag because they are updated frequently, and contain many
> not yet fit for public consumption. > breaking changes that are (by the author's design) not yet fit for public
> consumption.
Extended attributes and default values: Extended attributes and default values:
@ -505,9 +520,9 @@ tags: |
type=match,pattern=v(.*),group=1,value=v1.0.0 type=match,pattern=v(.*),group=1,value=v1.0.0
``` ```
Can create a regular expression for matching Git tag with a pattern and capturing group. Will be used on a Can create a regular expression for matching Git tag with a pattern and
[push tag event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push) but, you can also use capturing group. Will be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
a custom value through `value` attribute. but, you can also use a custom value through `value` attribute.
| Git tag | Pattern | Group | Output | | Git tag | Pattern | Group | Output |
|-------------------------|------------------|---------|------------------------| |-------------------------|------------------|---------|------------------------|
@ -534,9 +549,9 @@ tags: |
type=edge,branch=main type=edge,branch=main
``` ```
An `edge` tag reflects the last commit of the active branch on your Git repository. I usually prefer to use `edge` An `edge` tag reflects the last commit of the active branch on your Git
as a Docker tag for a better distinction or common pattern. This is also used by official images repository. I usually prefer to use `edge` as a Docker tag for a better
like [Alpine](https://hub.docker.com/_/alpine). distinction or common pattern. This is also used by official images like [Alpine](https://hub.docker.com/_/alpine).
Extended attributes and default values: Extended attributes and default values:
@ -558,17 +573,19 @@ tags: |
``` ```
This type handles Git ref (or reference) for the following events: This type handles Git ref (or reference) for the following events:
* `branch` ; eg. `refs/heads/master` * `branch` ; eg. `refs/heads/master`
* `tag` ; eg. `refs/tags/v1.0.0` * `tag` ; eg. `refs/tags/v1.0.0`
* `pr` ; eg. `refs/pull/318/merge` * `pr` ; eg. `refs/pull/318/merge`
| Event | Ref | Output | | Event | Ref | Output |
|-----------------|-------------------------------|-------------------------------| |---------------------|-------------------------------|------------------|
| `pull_request` | `refs/pull/2/merge` | `pr-2` | | `pull_request` | `refs/pull/2/merge` | `pr-2` |
| `push` | `refs/heads/master` | `master` | | `push` | `refs/heads/master` | `master` |
| `push` | `refs/heads/my/branch` | `my-branch` | | `push` | `refs/heads/my/branch` | `my-branch` |
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3` | | `push tag` | `refs/tags/v1.2.3` | `v1.2.3` |
| `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67` | | `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67` |
| `workflow_dispatch` | `refs/heads/master` | `master` |
Extended attributes and default values: Extended attributes and default values:
@ -628,7 +645,7 @@ tags: |
### Image name and tag sanitization ### Image name and tag sanitization
In order to comply with [the specification](https://docs.docker.com/engine/reference/commandline/tag/#extended-description), In order to comply with [the specification](https://docs.docker.com/engine/reference/commandline/tag/#description),
the image name components may contain lowercase letters, digits and separators. 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 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. dashes. A name component may not start or end with a separator.
@ -644,7 +661,9 @@ To ease the integration in your workflow, this action will automatically:
### Latest tag ### Latest tag
`latest` tag is handled through the [`flavor` input](#flavor-input). It will be generated by default (`auto` mode) for: `latest` tag is handled through the [`flavor` input](#flavor-input). It will be
generated by default (`auto` mode) for:
* [`type=ref,event=tag`](#typeref) * [`type=ref,event=tag`](#typeref)
* [`type=semver,pattern=...`](#typesemver) * [`type=semver,pattern=...`](#typesemver)
* [`type=match,pattern=...`](#typematch) * [`type=match,pattern=...`](#typematch)
@ -667,6 +686,24 @@ tags: |
type=raw,value=latest,enable={{is_default_branch}} type=raw,value=latest,enable={{is_default_branch}}
``` ```
### `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` |
### Global expressions ### Global expressions
The following [Handlebars' template](https://handlebarsjs.com/guide/) expressions The following [Handlebars' template](https://handlebarsjs.com/guide/) expressions
@ -685,12 +722,12 @@ tags: |
Returns the branch name that triggered the workflow run. Will be empty if not Returns the branch name that triggered the workflow run. Will be empty if not
a branch reference: a branch reference:
| Event | Ref | Output | | Event | Ref | Output |
|-----------------|-------------------------------|---------------------| |----------------|------------------------|-------------|
| `pull_request` | `refs/pull/2/merge` | | | `pull_request` | `refs/pull/2/merge` | |
| `push` | `refs/heads/master` | `master` | | `push` | `refs/heads/master` | `master` |
| `push` | `refs/heads/my/branch` | `my-branch` | | `push` | `refs/heads/my/branch` | `my-branch` |
| `push tag` | `refs/tags/v1.2.3` | | | `push tag` | `refs/tags/v1.2.3` | |
#### `{{tag}}` #### `{{tag}}`
@ -742,11 +779,11 @@ Returns the current date rendered by its [moment format](https://momentjs.com/do
### Major version zero ### Major version zero
Major version zero (`0.y.z`) is for initial development and **may** change at any time. This means the public API Major version zero (`0.y.z`) is for initial development and **may** change at
[**should not** be considered stable](https://semver.org/#spec-item-4). any time. This means the public API [**should not** be considered stable](https://semver.org/#spec-item-4).
In this case, Docker tag `0` **should not** be generated if you're using [`type=semver`](#typesemver) with `{{major}}` In this case, Docker tag `0` **should not** be generated if you're using [`type=semver`](#typesemver)
pattern. You can manage this behavior like this: with `{{major}}` pattern. You can manage this behavior like this:
```yaml ```yaml
# refs/tags/v0.1.2 # refs/tags/v0.1.2
@ -761,8 +798,8 @@ tags: |
### JSON output object ### JSON output object
The `json` output is a JSON object composed of the generated tags and labels so that you can reuse them further in your The `json` output is a JSON object composed of the generated tags and labels so
workflow using the [`fromJSON` function](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson): that you can reuse them further in your workflow using the [`fromJSON` function](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson):
```yaml ```yaml
- -
@ -802,18 +839,7 @@ labels generated are not suitable, you can overwrite them like this:
org.opencontainers.image.vendor=MyCompany org.opencontainers.image.vendor=MyCompany
``` ```
## Keep up-to-date with GitHub Dependabot ## Contributing
Since [Dependabot](https://docs.github.com/en/github/administering-a-repository/keeping-your-actions-up-to-date-with-github-dependabot) Want to contribute? Awesome! You can find information about contributing to
has [native GitHub Actions support](https://docs.github.com/en/github/administering-a-repository/configuration-options-for-dependency-updates#package-ecosystem), this project in the [CONTRIBUTING.md](/.github/CONTRIBUTING.md)
to enable it on your GitHub repo all you need to do is add the `.github/dependabot.yml` file:
```yaml
version: 2
updates:
# Maintain dependencies for GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "daily"
```

3
UPGRADE.md
View File

@ -2,7 +2,8 @@
## v2 to v3 ## v2 to v3
* Repository has been moved to docker org. Replace `crazy-max/ghaction-docker-meta@v2` with `docker/metadata-action@v4` * Repository has been moved to docker org. Replace `crazy-max/ghaction-docker-meta@v2`
with `docker/metadata-action@v4`
* The default bake target has been changed: `ghaction-docker-meta` > `docker-metadata-action` * The default bake target has been changed: `ghaction-docker-meta` > `docker-metadata-action`
## v1 to v2 ## v1 to v2

2
dist/index.js generated vendored
View File

File diff suppressed because one or more lines are too long

2
dist/index.js.map generated vendored
View File

File diff suppressed because one or more lines are too long

4
src/main.ts
View File

@ -72,9 +72,9 @@ async function run() {
core.endGroup(); core.endGroup();
setOutput('json', jsonOutput); setOutput('json', jsonOutput);
// Bake definition file // Bake file definition
const bakeFile: string = meta.getBakeFile(); const bakeFile: string = meta.getBakeFile();
core.startGroup(`Bake definition file`); core.startGroup(`Bake file definition`);
core.info(fs.readFileSync(bakeFile, 'utf8')); core.info(fs.readFileSync(bakeFile, 'utf8'));
core.endGroup(); core.endGroup();
setOutput('bake-file', bakeFile); setOutput('bake-file', bakeFile);

2
test/Dockerfile
View File

@ -1,3 +1,3 @@
# syntax=docker/dockerfile:1
FROM alpine FROM alpine
RUN echo "Hello world!" RUN echo "Hello world!"