Skip to content

Commit 210d783

Browse files
crazy-maxcrazy-max
authored
Merge pull request #235 from crazy-max/update-docs
docs: update
2 parents 8ed470c + 5f26473 commit 210d783

File tree

6 files changed

+116
-89
lines changed

6 files changed

+116
-89
lines changed

‎README.md‎

Lines changed: 109 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,9 @@
55

66
## About
77

8-
GitHub Action to extract metadata from Git reference and GitHub events.
9-
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.
8+
GitHub Action to extract metadata from Git reference and GitHub events. This action
9+
is particularly useful if used with [Docker Build Push](https://github.com/docker/build-push-action)
10+
action to tag and label Docker images.
1011

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

@@ -33,6 +34,7 @@ ___
3334
* [Notes](#notes)
3435
* [Image name and tag sanitization](#image-name-and-tag-sanitization)
3536
* [Latest tag](#latest-tag)
37+
* [`priority` attribute](#priority-attribute)
3638
* [Global expressions](#global-expressions)
3739
* [`{{branch}}`](#branch)
3840
* [`{{tag}}`](#tag)
@@ -43,7 +45,7 @@ ___
4345
* [Major version zero](#major-version-zero)
4446
* [JSON output object](#json-output-object)
4547
* [Overwrite labels](#overwrite-labels)
46-
* [Keep up-to-date with GitHub Dependabot](#keep-up-to-date-with-github-dependabot)
48+
* [Contributing](#contributing)
4749

4850
## Usage
4951

@@ -53,6 +55,7 @@ ___
5355
name: ci
5456

5557
on:
58+
workflow_dispatch:
5659
push:
5760
branches:
5861
- 'master'
@@ -92,13 +95,14 @@ jobs:
9295
labels: ${{ steps.meta.outputs.labels }}
9396
```
9497
95-
| Event | Ref | Docker Tags |
96-
|-----------------|-------------------------------|-------------------------------------|
97-
| `pull_request` | `refs/pull/2/merge` | `pr-2` |
98-
| `push` | `refs/heads/master` | `master` |
99-
| `push` | `refs/heads/releases/v1` | `releases-v1` |
100-
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3`, `latest` |
101-
| `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67`, `latest` |
98+
| Event | Ref | Docker Tags |
99+
|---------------------|-------------------------------|----------------------------|
100+
| `pull_request` | `refs/pull/2/merge` | `pr-2` |
101+
| `push` | `refs/heads/master` | `master` |
102+
| `push` | `refs/heads/releases/v1` | `releases-v1` |
103+
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3`, `latest` |
104+
| `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67`, `latest` |
105+
| `workflow_dispatch` | `refs/heads/master` | `master` |
102106

103107
### Semver
104108

@@ -162,8 +166,8 @@ jobs:
162166
### Bake definition
163167

164168
This action also handles a bake definition file that can be used with the
165-
[Docker Bake action](https://github.com/docker/bake-action). You just have to declare an empty target named
166-
`docker-metadata-action` and inherit from it.
169+
[Docker Bake action](https://github.com/docker/bake-action). You just have to
170+
declare an empty target named `docker-metadata-action` and inherit from it.
167171

168172
```hcl
169173
// docker-bake.hcl
@@ -223,7 +227,8 @@ jobs:
223227
targets: build
224228
```
225229

226-
Content of `${{ steps.meta.outputs.bake-file }}` file will look like this with `refs/tags/v1.2.3` ref:
230+
Content of `${{ steps.meta.outputs.bake-file }}` file will look like this with
231+
`refs/tags/v1.2.3` ref:
227232

228233
```json
229234
{
@@ -282,13 +287,13 @@ Following inputs can be used as `step.with` keys
282287

283288
Following outputs are available
284289

285-
| Name | Type | Description |
286-
|---------------|---------|-------------------------------------------------------------------------------|
287-
| `version` | String | Docker image version |
288-
| `tags` | String | Docker tags |
289-
| `labels` | String | Docker labels |
290-
| `json` | String | JSON output of tags and labels |
291-
| `bake-file` | File | [Bake definition file](https://github.com/docker/buildx#file-definition) path |
290+
| Name | Type | Description |
291+
|---------------|---------|--------------------------------------------------------------------------------------------|
292+
| `version` | String | Docker image version |
293+
| `tags` | String | Docker tags |
294+
| `labels` | String | Docker labels |
295+
| `json` | String | JSON output of tags and labels |
296+
| `bake-file` | File | [Bake file definition](https://docs.docker.com/build/customize/bake/file-definition/) path |
292297

293298
## `images` input
294299

@@ -325,13 +330,16 @@ flavor: |
325330
```
326331

327332
* `latest=<auto|true|false>`: Handle [latest tag](#latest-tag) (default `auto`)
328-
* `prefix=<string>,onlatest=<true|false>`: A global prefix for each generated tag and optionally for `latest`
329-
* `suffix=<string>,onlatest=<true|false>`: A global suffix for each generated tag and optionally for `latest`
333+
* `prefix=<string>,onlatest=<true|false>`: A global prefix for each generated
334+
tag and optionally for `latest`
335+
* `suffix=<string>,onlatest=<true|false>`: A global suffix for each generated
336+
tag and optionally for `latest`
330337

331338
## `tags` input
332339

333-
`tags` is the core input of this action as everything related to it will reflect the output metadata. This one is in
334-
the form of a key-value pair list in CSV format to remove limitations intrinsically linked to GitHub Actions
340+
`tags` is the core input of this action as everything related to it will
341+
reflect the output metadata. This one is in the form of a key-value pair list
342+
in CSV format to remove limitations intrinsically linked to GitHub Actions
335343
(only string format is handled in the input fields). Here is an example:
336344

337345
```yaml
@@ -359,7 +367,7 @@ Each entry is defined by a `type`, which are:
359367
And global attributes:
360368

361369
* `enable=<true|false>` enable this entry (default `true`)
362-
* `priority=<number>` priority to manage the order of tags
370+
* `priority=<number>` set tag [priority](#priority-attribute) order
363371
* `prefix=<string>` add prefix
364372
* `suffix=<string>` add suffix
365373

@@ -385,10 +393,11 @@ tags: |
385393
type=schedule,pattern={{date 'YYYYMMDD'}}
386394
```
387395

388-
Will be used on [schedule event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule).
396+
Will be used on [schedule event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
397+
398+
`pattern` is a specially crafted attribute to support [Handlebars' template](https://handlebarsjs.com/guide/)
399+
with the following expressions:
389400

390-
`pattern` is a specially crafted attribute to support [Handlebars' template](https://handlebarsjs.com/guide/) with
391-
the following expressions:
392401
* `date 'format'` ; render date by its [moment format](https://momentjs.com/docs/#/displaying/format/)
393402

394403
| Pattern | Output |
@@ -413,11 +422,13 @@ tags: |
413422
type=semver,pattern={{version}},value=v1.0.0
414423
```
415424

416-
Will be used on a [push tag event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push)
417-
and requires a valid [semver](https://semver.org/) Git tag, but you can also use a custom value through `value`
418-
attribute.
425+
Will be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
426+
and requires a valid [semver](https://semver.org/) Git tag, but you can also
427+
use a custom value through `value` attribute.
428+
429+
`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/)
430+
with the following expressions:
419431

420-
`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/) with the following expressions:
421432
* `raw` ; the actual tag
422433
* `version` ; shorthand for `{{major}}.{{minor}}.{{patch}}` (can include pre-release)
423434
* `major` ; major version identifier
@@ -436,9 +447,10 @@ attribute.
436447
| `v2.0.8-beta.67` | `{{version}}` | `2.0.8-beta.67` |
437448
| `v2.0.8-beta.67` | `{{major}}.{{minor}}` | `2.0.8-beta.67`* |
438449

439-
> *Pre-release (rc, beta, alpha) will only extend `{{version}}` (or `{{raw}}` if specified) as tag
440-
> because they are updated frequently, and contain many breaking changes that are (by the author's design)
441-
> not yet fit for public consumption.
450+
> *Pre-release (rc, beta, alpha) will only extend `{{version}}` (or `{{raw}}`
451+
> if specified) as tag because they are updated frequently, and contain many
452+
> breaking changes that are (by the author's design) not yet fit for public
453+
> consumption.
442454

443455
Extended attributes and default values:
444456

@@ -457,11 +469,13 @@ tags: |
457469
type=pep440,pattern={{version}},value=1.0.0
458470
```
459471

460-
Will be used on a [push tag event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push)
461-
and requires a Git tag that conforms to [PEP 440](https://www.python.org/dev/peps/pep-0440/), but you can also use a
462-
custom value through `value` attribute.
472+
Will be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
473+
and requires a Git tag that conforms to [PEP 440](https://www.python.org/dev/peps/pep-0440/),
474+
but you can also use a custom value through `value` attribute.
475+
476+
`pattern` attribute supports [Handlebars template](https://handlebarsjs.com/guide/)
477+
with the following expressions:
463478

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

485-
> *dev/pre/post release will only extend `{{version}}` (or `{{raw}}` if specified) as tag
486-
> because they are updated frequently, and contain many breaking changes that are (by the author's design)
487-
> not yet fit for public consumption.
499+
> *dev/pre/post release will only extend `{{version}}` (or `{{raw}}` if
500+
> specified) as tag because they are updated frequently, and contain many
501+
> breaking changes that are (by the author's design) not yet fit for public
502+
> consumption.
488503

489504
Extended attributes and default values:
490505

@@ -505,9 +520,9 @@ tags: |
505520
type=match,pattern=v(.*),group=1,value=v1.0.0
506521
```
507522

508-
Can create a regular expression for matching Git tag with a pattern and capturing group. Will be used on a
509-
[push tag event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push) but, you can also use
510-
a custom value through `value` attribute.
523+
Can create a regular expression for matching Git tag with a pattern and
524+
capturing group. Will be used on a [push tag event](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push)
525+
but, you can also use a custom value through `value` attribute.
511526

512527
| Git tag | Pattern | Group | Output |
513528
|-------------------------|------------------|---------|------------------------|
@@ -534,9 +549,9 @@ tags: |
534549
type=edge,branch=main
535550
```
536551

537-
An `edge` tag reflects the last commit of the active branch on your Git repository. I usually prefer to use `edge`
538-
as a Docker tag for a better distinction or common pattern. This is also used by official images
539-
like [Alpine](https://hub.docker.com/_/alpine).
552+
An `edge` tag reflects the last commit of the active branch on your Git
553+
repository. I usually prefer to use `edge` as a Docker tag for a better
554+
distinction or common pattern. This is also used by official images like [Alpine](https://hub.docker.com/_/alpine).
540555

541556
Extended attributes and default values:
542557

@@ -558,17 +573,19 @@ tags: |
558573
```
559574

560575
This type handles Git ref (or reference) for the following events:
576+
561577
* `branch` ; eg. `refs/heads/master`
562578
* `tag` ; eg. `refs/tags/v1.0.0`
563579
* `pr` ; eg. `refs/pull/318/merge`
564580

565-
| Event | Ref | Output |
566-
|-----------------|-------------------------------|-------------------------------|
567-
| `pull_request` | `refs/pull/2/merge` | `pr-2` |
568-
| `push` | `refs/heads/master` | `master` |
569-
| `push` | `refs/heads/my/branch` | `my-branch` |
570-
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3` |
571-
| `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67` |
581+
| Event | Ref | Output |
582+
|---------------------|-------------------------------|------------------|
583+
| `pull_request` | `refs/pull/2/merge` | `pr-2` |
584+
| `push` | `refs/heads/master` | `master` |
585+
| `push` | `refs/heads/my/branch` | `my-branch` |
586+
| `push tag` | `refs/tags/v1.2.3` | `v1.2.3` |
587+
| `push tag` | `refs/tags/v2.0.8-beta.67` | `v2.0.8-beta.67` |
588+
| `workflow_dispatch` | `refs/heads/master` | `master` |
572589

573590
Extended attributes and default values:
574591

@@ -628,7 +645,7 @@ tags: |
628645

629646
### Image name and tag sanitization
630647

631-
In order to comply with [the specification](https://docs.docker.com/engine/reference/commandline/tag/#extended-description),
648+
In order to comply with [the specification](https://docs.docker.com/engine/reference/commandline/tag/#description),
632649
the image name components may contain lowercase letters, digits and separators.
633650
A separator is defined as a period, one or two underscores, or one or more
634651
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:
644661

645662
### Latest tag
646663

647-
`latest` tag is handled through the [`flavor` input](#flavor-input). It will be generated by default (`auto` mode) for:
664+
`latest` tag is handled through the [`flavor` input](#flavor-input). It will be
665+
generated by default (`auto` mode) for:
666+
648667
* [`type=ref,event=tag`](#typeref)
649668
* [`type=semver,pattern=...`](#typesemver)
650669
* [`type=match,pattern=...`](#typematch)
@@ -667,6 +686,24 @@ tags: |
667686
type=raw,value=latest,enable={{is_default_branch}}
668687
```
669688

689+
### `priority` attribute
690+
691+
`priority=<int>` attribute is used to sort tags in the final list. The higher
692+
the value, the higher the priority. The first tag in the list (higher priority)
693+
will be used as the image version for generated OCI label and [`version` output](#outputs).
694+
Each tags `type` attribute has a default priority:
695+
696+
| Attribute | Default priority |
697+
|------------|------------------|
698+
| `schedule` | `1000` |
699+
| `semver` | `900` |
700+
| `pep440` | `900` |
701+
| `match` | `800` |
702+
| `edge` | `700` |
703+
| `ref` | `600` |
704+
| `raw` | `200` |
705+
| `sha` | `100` |
706+
670707
### Global expressions
671708

672709
The following [Handlebars' template](https://handlebarsjs.com/guide/) expressions
@@ -685,12 +722,12 @@ tags: |
685722
Returns the branch name that triggered the workflow run. Will be empty if not
686723
a branch reference:
687724

688-
| Event | Ref | Output |
689-
|-----------------|-------------------------------|---------------------|
690-
| `pull_request` | `refs/pull/2/merge` | |
691-
| `push` | `refs/heads/master` | `master` |
692-
| `push` | `refs/heads/my/branch` | `my-branch` |
693-
| `push tag` | `refs/tags/v1.2.3` | |
725+
| Event | Ref | Output |
726+
|----------------|------------------------|-------------|
727+
| `pull_request` | `refs/pull/2/merge` | |
728+
| `push` | `refs/heads/master` | `master` |
729+
| `push` | `refs/heads/my/branch` | `my-branch` |
730+
| `push tag` | `refs/tags/v1.2.3` | |
694731

695732
#### `{{tag}}`
696733

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

743780
### Major version zero
744781

745-
Major version zero (`0.y.z`) is for initial development and **may** change at any time. This means the public API
746-
[**should not** be considered stable](https://semver.org/#spec-item-4).
782+
Major version zero (`0.y.z`) is for initial development and **may** change at
783+
any time. This means the public API [**should not** be considered stable](https://semver.org/#spec-item-4).
747784

748-
In this case, Docker tag `0` **should not** be generated if you're using [`type=semver`](#typesemver) with `{{major}}`
749-
pattern. You can manage this behavior like this:
785+
In this case, Docker tag `0` **should not** be generated if you're using [`type=semver`](#typesemver)
786+
with `{{major}}` pattern. You can manage this behavior like this:
750787

751788
```yaml
752789
# refs/tags/v0.1.2
@@ -761,8 +798,8 @@ tags: |
761798

762799
### JSON output object
763800

764-
The `json` output is a JSON object composed of the generated tags and labels so that you can reuse them further in your
765-
workflow using the [`fromJSON` function](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson):
801+
The `json` output is a JSON object composed of the generated tags and labels so
802+
that you can reuse them further in your workflow using the [`fromJSON` function](https://docs.github.com/en/actions/learn-github-actions/expressions#fromjson):
766803

767804
```yaml
768805
-
@@ -802,18 +839,7 @@ labels generated are not suitable, you can overwrite them like this:
802839
org.opencontainers.image.vendor=MyCompany
803840
```
804841

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

811-
```yaml
812-
version: 2
813-
updates:
814-
# Maintain dependencies for GitHub Actions
815-
- package-ecosystem: "github-actions"
816-
directory: "/"
817-
schedule:
818-
interval: "daily"
819-
```
844+
Want to contribute? Awesome! You can find information about contributing to
845+
this project in the [CONTRIBUTING.md](/.github/CONTRIBUTING.md)

‎UPGRADE.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
## v2 to v3
44

5-
* Repository has been moved to docker org. Replace `crazy-max/ghaction-docker-meta@v2` with `docker/metadata-action@v4`
5+
* Repository has been moved to docker org. Replace `crazy-max/ghaction-docker-meta@v2`
6+
with `docker/metadata-action@v4`
67
* The default bake target has been changed: `ghaction-docker-meta` > `docker-metadata-action`
78

89
## v1 to v2

‎dist/index.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/index.js.map‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/main.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,9 @@ async function run() {
7272
core.endGroup();
7373
setOutput('json', jsonOutput);
7474

75-
// Bake definition file
75+
// Bake file definition
7676
const bakeFile: string = meta.getBakeFile();
77-
core.startGroup(`Bake definition file`);
77+
core.startGroup(`Bake file definition`);
7878
core.info(fs.readFileSync(bakeFile, 'utf8'));
7979
core.endGroup();
8080
setOutput('bake-file', bakeFile);

0 commit comments

Comments
 (0)