Skip to content

Commit b0b9842

Browse files
br3ndonlandbr3ndonland
committed
feat: enable customization of annotations+labels
Signed-off-by: Brendon Smith <bws@bws.bio>
1 parent ed95091 commit b0b9842

File tree

4 files changed

+320
-100
lines changed

4 files changed

+320
-100
lines changed

‎README.md‎

Lines changed: 127 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,11 @@ ___
3434
* [`type=ref`](#typeref)
3535
* [`type=raw`](#typeraw)
3636
* [`type=sha`](#typesha)
37+
* [`annotations` and `labels` inputs](#annotations-and-labels-inputs)
38+
* [Default labels and annotations](#default-labels-and-annotations)
39+
* [Customize labels and annotations](#customize-labels-and-annotations)
40+
* [Annotation outputs](#annotation-outputs)
41+
* [Annotation levels](#annotation-levels)
3742
* [Notes](#notes)
3843
* [Image name and tag sanitization](#image-name-and-tag-sanitization)
3944
* [Latest tag](#latest-tag)
@@ -49,8 +54,6 @@ ___
4954
* [`{{commit_date '<format>' tz='<timezone>'}}`](#commit_date-format-tztimezone)
5055
* [Major version zero](#major-version-zero)
5156
* [JSON output object](#json-output-object)
52-
* [Overwrite labels and annotations](#overwrite-labels-and-annotations)
53-
* [Annotations](#annotations)
5457
* [Contributing](#contributing)
5558

5659
## Usage
@@ -745,6 +748,128 @@ tags: |
745748
type=sha,enable=true,priority=100,prefix=sha-,suffix=,format=short
746749
```
747750

751+
## `annotations` and `labels` inputs
752+
753+
### Default labels and annotations
754+
755+
The action will set the following default labels and annotations based on repository metadata:
756+
757+
- `org.opencontainers.image.title`
758+
- `org.opencontainers.image.description`
759+
- `org.opencontainers.image.url`
760+
- `org.opencontainers.image.source`
761+
- `org.opencontainers.image.version`
762+
- `org.opencontainers.image.created`
763+
- `org.opencontainers.image.revision`
764+
- `org.opencontainers.image.licenses`
765+
766+
### Customize labels and annotations
767+
768+
If some [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
769+
generated are not suitable as labels/annotations, you can overwrite them like
770+
this:
771+
772+
```yaml
773+
-
774+
name: Docker meta
775+
id: meta
776+
uses: docker/metadata-action@v5
777+
with:
778+
images: name/app
779+
labels: |
780+
maintainer=CrazyMax
781+
org.opencontainers.image.title=MyCustomTitle
782+
org.opencontainers.image.description=Another description
783+
org.opencontainers.image.vendor=MyCompany
784+
```
785+
786+
Alternatively, you may wish to omit certain labels and annotations from the action output. For example, you may have `LABEL` directives in a Dockerfile that you would prefer to use instead of the labels set by this action. You can omit labels and annotations with `enable=false`.
787+
788+
```yaml
789+
-
790+
name: Docker meta
791+
id: meta
792+
uses: docker/metadata-action@v5
793+
with:
794+
images: name/app
795+
labels: |
796+
name=org.opencontainers.image.url,enable=false
797+
```
798+
799+
### Annotation outputs
800+
801+
Since Buildx 0.12, it is possible to set annotations to your image through the
802+
`--annotation` flag.
803+
804+
With the [`build-push-action`](https://github.com/docker/build-push-action/),
805+
you can set the `annotations` input with the value of the `annotations` output
806+
of the `metadata-action`:
807+
808+
```yaml
809+
-
810+
name: Docker meta
811+
uses: docker/metadata-action@v5
812+
with:
813+
images: name/app
814+
-
815+
name: Build and push
816+
uses: docker/build-push-action@v6
817+
with:
818+
tags: ${{ steps.meta.outputs.tags }}
819+
annotations: ${{ steps.meta.outputs.annotations }}
820+
```
821+
822+
The same can be done with the [`bake-action`](https://github.com/docker/bake-action/):
823+
824+
```yaml
825+
-
826+
name: Docker meta
827+
uses: docker/metadata-action@v5
828+
with:
829+
images: name/app
830+
-
831+
name: Build
832+
uses: docker/bake-action@v6
833+
with:
834+
files: |
835+
./docker-bake.hcl
836+
cwd://${{ steps.meta.outputs.bake-file-tags }}
837+
cwd://${{ steps.meta.outputs.bake-file-annotations }}
838+
targets: build
839+
```
840+
841+
### Annotation levels
842+
843+
Note that annotations can be attached at many different levels within a manifest.
844+
By default, the generated annotations will be attached to image manifests,
845+
but different registries may expect annotations at different places;
846+
a common practice is to read annotations at _image indexes_ if present,
847+
which are often used by multi-arch builds to index platform-specific images.
848+
If you want to specify level(s) for your annotations, you can use the
849+
[`DOCKER_METADATA_ANNOTATIONS_LEVELS` environment variable](#environment-variables)
850+
with a comma separated list of all levels the annotations should be attached to (defaults to `manifest`).
851+
The following configuration demonstrates the ability to attach annotations to both image manifests and image indexes,
852+
though your registry may only need annotations at the index level. (That is, `index` alone may be enough.)
853+
Please consult the documentation of your registry.
854+
855+
```yaml
856+
-
857+
name: Docker meta
858+
uses: docker/metadata-action@v5
859+
with:
860+
images: name/app
861+
env:
862+
DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
863+
-
864+
name: Build and push
865+
uses: docker/build-push-action@v6
866+
with:
867+
tags: ${{ steps.meta.outputs.tags }}
868+
annotations: ${{ steps.meta.outputs.annotations }}
869+
```
870+
871+
More information about annotations in the [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md).
872+
748873
## Notes
749874

750875
### Image name and tag sanitization
@@ -955,98 +1080,6 @@ that you can reuse them further in your workflow using the [`fromJSON` function]
9551080
REVISION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}
9561081
```
9571082

958-
### Overwrite labels and annotations
959-
960-
If some [OCI Image Format Specification](https://github.com/opencontainers/image-spec/blob/master/annotations.md)
961-
generated are not suitable as labels/annotations, you can overwrite them like
962-
this:
963-
964-
```yaml
965-
-
966-
name: Docker meta
967-
id: meta
968-
uses: docker/metadata-action@v5
969-
with:
970-
images: name/app
971-
labels: |
972-
maintainer=CrazyMax
973-
org.opencontainers.image.title=MyCustomTitle
974-
org.opencontainers.image.description=Another description
975-
org.opencontainers.image.vendor=MyCompany
976-
```
977-
978-
### Annotations
979-
980-
Since Buildx 0.12, it is possible to set annotations to your image through the
981-
`--annotation` flag.
982-
983-
With the [`build-push-action`](https://github.com/docker/build-push-action/),
984-
you can set the `annotations` input with the value of the `annotations` output
985-
of the `metadata-action`:
986-
987-
```yaml
988-
-
989-
name: Docker meta
990-
uses: docker/metadata-action@v5
991-
with:
992-
images: name/app
993-
-
994-
name: Build and push
995-
uses: docker/build-push-action@v6
996-
with:
997-
tags: ${{ steps.meta.outputs.tags }}
998-
annotations: ${{ steps.meta.outputs.annotations }}
999-
```
1000-
1001-
The same can be done with the [`bake-action`](https://github.com/docker/bake-action/):
1002-
1003-
```yaml
1004-
-
1005-
name: Docker meta
1006-
uses: docker/metadata-action@v5
1007-
with:
1008-
images: name/app
1009-
-
1010-
name: Build
1011-
uses: docker/bake-action@v6
1012-
with:
1013-
files: |
1014-
./docker-bake.hcl
1015-
cwd://${{ steps.meta.outputs.bake-file-tags }}
1016-
cwd://${{ steps.meta.outputs.bake-file-annotations }}
1017-
targets: build
1018-
```
1019-
1020-
Note that annotations can be attached at many different levels within a manifest.
1021-
By default, the generated annotations will be attached to image manifests,
1022-
but different registries may expect annotations at different places;
1023-
a common practice is to read annotations at _image indexes_ if present,
1024-
which are often used by multi-arch builds to index platform-specific images.
1025-
If you want to specify level(s) for your annotations, you can use the
1026-
[`DOCKER_METADATA_ANNOTATIONS_LEVELS` environment variable](#environment-variables)
1027-
with a comma separated list of all levels the annotations should be attached to (defaults to `manifest`).
1028-
The following configuration demonstrates the ability to attach annotations to both image manifests and image indexes,
1029-
though your registry may only need annotations at the index level. (That is, `index` alone may be enough.)
1030-
Please consult the documentation of your registry.
1031-
1032-
```yaml
1033-
-
1034-
name: Docker meta
1035-
uses: docker/metadata-action@v5
1036-
with:
1037-
images: name/app
1038-
env:
1039-
DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
1040-
-
1041-
name: Build and push
1042-
uses: docker/build-push-action@v6
1043-
with:
1044-
tags: ${{ steps.meta.outputs.tags }}
1045-
annotations: ${{ steps.meta.outputs.annotations }}
1046-
```
1047-
1048-
More information about annotations in the [BuildKit documentation](https://github.com/moby/buildkit/blob/master/docs/annotations.md).
1049-
10501083
## Contributing
10511084

10521085
Want to contribute? Awesome! You can find information about contributing to

‎__tests__/annotation.test.ts‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
import {describe, expect, test} from '@jest/globals';
2+
3+
import {Transform, Annotation} from '../src/annotation';
4+
5+
describe('annotation transform', () => {
6+
test.each([
7+
[
8+
[`org.opencontainers.image.version=1.1.1`],
9+
[
10+
{
11+
name: `org.opencontainers.image.version`,
12+
value: `1.1.1`,
13+
enable: true
14+
}
15+
] as Annotation[],
16+
false
17+
],
18+
[
19+
[`name=my.annotation,value="my value",enable=true`],
20+
[
21+
{
22+
name: `my.annotation`,
23+
value: `"my value"`,
24+
enable: true
25+
}
26+
] as Annotation[],
27+
false
28+
],
29+
[
30+
[`name=my.annotation,value=myvalue,enable=false`],
31+
[
32+
{
33+
name: `my.annotation`,
34+
value: `myvalue`,
35+
enable: false
36+
}
37+
] as Annotation[],
38+
false
39+
],
40+
[
41+
[`my.annotation=my value`],
42+
[
43+
{
44+
name: `my.annotation`,
45+
value: `my value`,
46+
enable: true
47+
}
48+
] as Annotation[],
49+
false
50+
],
51+
[
52+
[`name=,value=val`], // empty name
53+
undefined,
54+
true
55+
],
56+
[
57+
[`name=org.opencontainers.image.url,enable=false`], // empty value
58+
[
59+
{
60+
name: `org.opencontainers.image.url`,
61+
value: null,
62+
enable: false
63+
}
64+
] as Annotation[],
65+
false
66+
],
67+
[
68+
[`name=my.annotation,value=myvalue,enable=bar`], // invalid enable
69+
undefined,
70+
true
71+
]
72+
])('given %p', async (l: string[], expected: Annotation[] | undefined, invalid: boolean) => {
73+
try {
74+
const annotations = Transform(l);
75+
expect(annotations).toEqual(expected);
76+
} catch (err) {
77+
if (!invalid) {
78+
console.error(err);
79+
}
80+
expect(invalid).toBeTruthy();
81+
}
82+
});
83+
});

0 commit comments

Comments
 (0)