feat: enable customization of annotations+labels

[br3ndonland]

Description

Closes #243

Currently, the annotations: and labels: inputs do not support the same degree of customization as other inputs like images:.

This can have effects on output metadata, particularly for labels. The action currently sets some non-configurable labels.

metadata-action/src/meta.ts

Lines 542 to 549 in ed95091

	`org.opencontainers.image.title=${this.repo.name || ''}`,
	`org.opencontainers.image.description=${this.repo.description || ''}`,
	`org.opencontainers.image.url=${this.repo.html_url || ''}`,
	`org.opencontainers.image.source=${this.repo.html_url || ''}`,
	`org.opencontainers.image.version=${this.version.main || ''}`,
	`org.opencontainers.image.created=${this.date.toISOString()}`,
	`org.opencontainers.image.revision=${this.context.sha || ''}`,
	`org.opencontainers.image.licenses=${this.repo.license?.spdx_id || ''}`

If these labels are passed into Buildx with docker/build-push-action, they will override LABEL directives in the Dockerfile. It could therefore be helpful to allow users to enable or disable certain labels and annotations if they would prefer to set them with LABEL directives instead.

Changes

This PR will add customizations for the annotations: and labels: inputs like the ones supported for the images: input.

Global expressions will be supported.

Related

• Add label customization/options #243
• docker/metadata-action README: Global expressions
• Docker Docs: Docker Build - CI - GitHub Actions - Annotations

[polarathene]

I think you can simplify this PR quite a bit by getting opt-out functionality via empty annotation values (some defaults like licenses can result in empty strings).

The only other related functionality that comes to mind is if someone were to want more control between index and manifest annotation assignment. I don't think there's an open issue with a use-case requesting such support however, so for now I'd just favor the opt-out via empty value approach, it'd reduce your code contribution quite a bit and simplify the UX for users instead of adding extra complexity.

[polarathene]

I am not sure about this syntax, would it make more sense to just opt-out via setting an empty value instead? Slight more terse, and doesn't introduce an alternative syntax.

---

I had suggested that in a recent issue I opened. Some of the default values can already produce an empty value, but are still applied which also overrides the LABEL if present in a Dockerfile.

I'm not sure how often someone would want to set an empty annotation or label, I suppose for LABEL it might be to "unset" one that was inherited? If so they could still do that within their Dockerfile, so I don't think it's relevant for docker/metadata-action to support keeping empty annotations/labels to apply.

However my request would be a breaking change to anyone who did rely on that.

[polarathene]

It would also have been helpful for review if you had used separate commits while shifting the bulk of this README around before adding this YAML snippet (and preceding paragraph_), as that'd make the diff much simpler to follow and grok.

[polarathene]

It might be helpful to better communicate better how those values are acquired? While it's useful to know what defaults are being provided by the action, it's also helpful to know what to expect those values are without having to experiment.

I opened an issue requesting better documenting the defaults. The repository metadata this action sources is equivalent to what you'd get from querying the repository metadata via the HTTP API (https://api.github.com/repos/<OWNER>/<REPO>, for example see the metadata for this repo) which as you mentioned which will cover this subset of OCI annotations:

org.opencontainers.image.title=${{ github.event.repository.name }}
org.opencontainers.image.description=${{ github.event.repository.description }}
org.opencontainers.image.url==${{ github.event.repository.html_url }}
org.opencontainers.image.source=${{ github.event.repository.html_url }}
org.opencontainers.image.licenses=${{ github.event.repository.license?.spdx_id }}

Of which as my issue describes licenses cannot be expressed that way explicitly, and would be more verbose when an expression like {{ license }} could be added to the action to better support it (sometimes it's preferable to configure explicitly for visibility).

The remaining are similar to doing this (version is actually dependent upon tags input processing, not a tag ref type):

org.opencontainers.image.version=${{ github.ref_type == 'tag' && github.ref_name }}
org.opencontainers.image.created={{ date }}
org.opencontainers.image.revision=${{ github.sha }}

version is the more difficult one to express... it's actually this.version.main and refers to the first tag value produced from the tags input (after sorting by priority values IIRC).

• As the link mentions this behaviour is already documented in the priorities section (another reference for clarity as it's sometimes misunderstood), but would be relevant context to include here too when describing defaults.
• {{ version }} as an expression for use in labels/annotations inputs was requested, but it might potentially introduce confusion with the existing {{ version }} (used in pattern for semver/pep440 tag types, which has a known gotcha that users need to be careful of). {{ image_version }} / {{ primary_tag }} might be more accurate (since the value may not represent a version, but could by any tag value like main or a commit hash).

[polarathene]

The only customization is opt-out of defaults (which could be covered in the defaults section), at which point you're back to overwriting the defaults (also valid for explaining opt-out) or adding your own (which implicitly overwrites defaults).

Additionally, there's no need to repeat labels and annotations for the subsections linked. Previously these were under a "Notes" section, so the added context was necessary.