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.

---

BTW, it would have been helpful for review if you had used a separate commit for shifting the bulk of the README changes around before adding the YAML snippet (and preceding paragraph), as that'd have made the diff much simpler to follow and grok.

[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 opt-out by setting an empty value 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) but I don't think there's a good reason to expect/want that to occur?
• 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 setting empty values to override image labels.

---

An alternative could be a separate input to provide a list of default labels/annotations to exclude? They're all using the same namespace and defaults aren't configurable, so it's probably okay to take that approach instead too 🤷‍♂️ (then it avoids the risk of breaking anyone that might expect empty values to be supported + less verbose if disabling multiple labels)

[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 have opened an issue requesting better documenting the defaults as sometimes it's preferable to configure explicitly for visibility.

EDIT: I moved the bulk of this comment to the associated issue for documenting defaults.

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