Skip to content

Commit

Permalink
Merge pull request #235 from crazy-max/update-docs
Browse files Browse the repository at this point in the history 
docs: update
  • Loading branch information
@crazy-max
crazy-max authored Oct 8, 2022
2 parents 8ed470c + 5f26473 commit 210d783
Show file tree
Hide file tree
Showing 6 changed files with 116 additions and 89 deletions.
192 changes: 109 additions & 83 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@

## About

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.
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.

![Screenshot](.github/metadata-action.png)

Expand All @@ -33,6 +34,7 @@ ___
* [Notes](#notes)
* [Image name and tag sanitization](#image-name-and-tag-sanitization)
* [Latest tag](#latest-tag)
* [`priority` attribute](#priority-attribute)
* [Global expressions](#global-expressions)
* [`{{branch}}`](#branch)
* [`{{tag}}`](#tag)
Expand All @@ -43,7 +45,7 @@ ___
* [Major version zero](#major-version-zero)
* [JSON output object](#json-output-object)
* [Overwrite labels](#overwrite-labels)
* [Keep up-to-date with GitHub Dependabot](#keep-up-to-date-with-github-dependabot)
* [Contributing](#contributing)

## Usage

Expand All @@ -53,6 +55,7 @@ ___
name: ci

on:
workflow_dispatch:
push:
branches:
- 'master'
Expand Down Expand Up @@ -92,13 +95,14 @@ jobs:
labels: ${{ steps.meta.outputs.labels }}
```
| 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` |
| 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` |

### Semver

Expand Down Expand Up @@ -162,8 +166,8 @@ jobs:
### Bake definition

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-metadata-action` and inherit from it.
[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.

```hcl
// docker-bake.hcl
Expand Down Expand Up @@ -223,7 +227,8 @@ jobs:
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
{
Expand Down Expand Up @@ -282,13 +287,13 @@ Following inputs can be used as `step.with` keys

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 definition file](https://github.com/docker/buildx#file-definition) path |
| 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 |

## `images` input

Expand Down Expand Up @@ -325,13 +330,16 @@ flavor: |
```

* `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`
* `suffix=<string>,onlatest=<true|false>`: A global suffix for each generated tag and optionally for `latest`
* `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`

## `tags` input

`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
`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
(only string format is handled in the input fields). Here is an example:

```yaml
Expand Down Expand Up @@ -359,7 +367,7 @@ Each entry is defined by a `type`, which are:
And global attributes:

* `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
* `suffix=<string>` add suffix

Expand All @@ -385,10 +393,11 @@ tags: |
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/)

| Pattern | Output |
Expand All @@ -413,11 +422,13 @@ tags: |
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)
and requires a valid [semver](https://semver.org/) Git tag, but you can also use a custom value through `value`
attribute.
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:

`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/) with the following expressions:
* `raw` ; the actual tag
* `version` ; shorthand for `{{major}}.{{minor}}.{{patch}}` (can include pre-release)
* `major` ; major version identifier
Expand All @@ -436,9 +447,10 @@ attribute.
| `v2.0.8-beta.67` | `{{version}}` | `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
> because they are updated frequently, and contain many breaking changes that are (by the author's design)
> not yet fit for public consumption.
> *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.

Extended attributes and default values:

Expand All @@ -457,11 +469,13 @@ tags: |
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)
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.
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:

`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/) with the following expressions:
* `raw` ; the actual tag
* `version` ; cleaned version
* `major` ; major version identifier
Expand All @@ -482,9 +496,10 @@ custom value through `value` attribute.
| `1.2.3beta2` | `{{major}}.{{minor}}` | `1.2.3b2`* |
| `1.0dev4` | `{{major}}.{{minor}}` | `1.0.dev4`* |

> *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.
> *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.

Extended attributes and default values:

Expand All @@ -505,9 +520,9 @@ tags: |
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
[push tag event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push) but, you can also use
a custom value through `value` attribute.
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.

| Git tag | Pattern | Group | Output |
|-------------------------|------------------|---------|------------------------|
Expand All @@ -534,9 +549,9 @@ tags: |
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`
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).
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).

Extended attributes and default values:

Expand All @@ -558,17 +573,19 @@ tags: |
```

This type handles Git ref (or reference) for the following events:

* `branch` ; eg. `refs/heads/master`
* `tag` ; eg. `refs/tags/v1.0.0`
* `pr` ; eg. `refs/pull/318/merge`

| 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` |
| 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` |

Extended attributes and default values:

Expand Down Expand Up @@ -628,7 +645,7 @@ tags: |

### 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.
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.
Expand All @@ -644,7 +661,9 @@ To ease the integration in your workflow, this action will automatically:

### 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=semver,pattern=...`](#typesemver)
* [`type=match,pattern=...`](#typematch)
Expand All @@ -667,6 +686,24 @@ tags: |
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

The following [Handlebars' template](https://handlebarsjs.com/guide/) expressions
Expand All @@ -685,12 +722,12 @@ tags: |
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` | |
| 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}}`

Expand Down Expand Up @@ -742,11 +779,11 @@ Returns the current date rendered by its [moment format](https://momentjs.com/do

### Major version zero

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).
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).

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:
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:

```yaml
# refs/tags/v0.1.2
Expand All @@ -761,8 +798,8 @@ tags: |

### 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
workflow using the [`fromJSON` function](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson):
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):

```yaml
-
Expand Down Expand Up @@ -802,18 +839,7 @@ labels generated are not suitable, you can overwrite them like this:
org.opencontainers.image.vendor=MyCompany
```

## Keep up-to-date with GitHub Dependabot

Since [Dependabot](https://docs.github.com/en/github/administering-a-repository/keeping-your-actions-up-to-date-with-github-dependabot)
has [native GitHub Actions support](https://docs.github.com/en/github/administering-a-repository/configuration-options-for-dependency-updates#package-ecosystem),
to enable it on your GitHub repo all you need to do is add the `.github/dependabot.yml` file:
## Contributing

```yaml
version: 2
updates:
# Maintain dependencies for GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "daily"
```
Want to contribute? Awesome! You can find information about contributing to
this project in the [CONTRIBUTING.md](/.github/CONTRIBUTING.md)
3 changes: 2 additions & 1 deletion UPGRADE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

## 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`

## v1 to v2
Expand Down
2 changes: 1 addition & 1 deletion dist/index.js
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion dist/index.js.map
View file

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions src/main.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,9 @@ async function run() {
core.endGroup();
setOutput('json', jsonOutput);

// Bake definition file
// Bake file definition
const bakeFile: string = meta.getBakeFile();
core.startGroup(`Bake definition file`);
core.startGroup(`Bake file definition`);
core.info(fs.readFileSync(bakeFile, 'utf8'));
core.endGroup();
setOutput('bake-file', bakeFile);
Expand Down
Loading

0 comments on commit 210d783

Please sign in to comment.