Better document implicit defaults of `labels`/`annotations`

[polarathene]

Description

The relevant source is reasonably straight-forward to interpret and unlikely to change:

metadata-action/src/meta.ts

Lines 540 to 550 in ed95091

	private getOCIAnnotationsWithCustoms(extra: string[]): Array<string> {
	const res: Array<string> = [
	`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 || ''}`
	];

NOTE: Presently some of those defaults cannot be easily expressed explicitly (sometimes preferable as visibility for maintainers vs implicit knowledge), but this would be much simpler to document if the following was resolved:

• Empty labels should be omitted #584
• Add a {{ license }} global expression #585
• Add a {{ main_version }} expression #591

org.opencontainers.image.version in particular has been a common caveat users have tripped up on. More relevant direct documentation on this default could link to the priority attributes section for improved visibility/discovery and thus awareness (instead of encountering it after tags are published). See the last section of my next comment for more info.

[polarathene]

Annotations - Repository metadata defaults (rarely changing)

The repository metadata that docker/metadata-action sources is equivalent to what you'd get from querying the repository metadata via the HTTP API (for an example see the metadata returned for this repo).

That metadata will cover this subset of defaults supplied by the action (which are from the OCI spec pre-defined 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 }}

NOTE: license?.spdx_id is invalid and would instead be more verbose, which is described in my feature request for {{ license }} expression.

Annotations - Remaining defaults (dynamic context)

The remaining OCI annotations are similar to doing the following (NOTE: the image.version default is dependent upon having already processed the tags input, as such the value assigned is actually context dependent):

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

NOTE: github.sha might not be accurate here either, depending on the context input. The docs on that input are a bit sparse, I haven't investigated further but assume it either gets git information from a cloned repo locally or querying the repo in a manner that it's results for the commit sha would differ from the workflows github context?

org.opencontainers.image.created (possibly share advice to prefer commit_date)

org.opencontainers.image.created might be worthwhile to advise a tip for using the date of a commit, rather than of the workflow run occurring? This is supported via the {{ commit_date }} expression.

It would help with reproducible builds for runs on the same commit (OCI spec however technically encourages actual build time of the image, which can be associated to a specific CI run):

labels: |
  # Prevent the default from the action (avoid unnecessarily changing the image config digest):
  org.opencontainers.image.created=
annotations: |
  org.opencontainers.image.created={{ commit_date 'YYYY-MM-DDTHH:mm:ss.SSS[Z]' }}

As defined in the OCI spec for pre-defined annotations this annotation should format it's date to be compliant with RFC 3339 (a profile of ISO 8601 which covers a simple subset of formats).

• Source reference for the {{ commit_date }} expression (Associated PR).
• The commit date is acquired differently based on the context used. With the default workflow context potentially falling back to the current timestamp of the workflow run if information on the commit date is missing (which has been reported before, appears to be due to using a self-hosted runner).
• NOTE: Like with {{ date }}, the current docs for the {{ commit_date }} expression doesn't contain an example for outputting a RFC 3339 compliant timestamp.
  • The timestamp should be formatted to RFC 3339 (as per the ABNF grammar for date-time which translates to <full-date>T<full-time>[time-secfrac]<Z | <time-numoffset>>). For commit_date/date expressions of this action you would provide 'YYYY-MM-DDTHH:mm:ss.SSS[Z]' (.SSS is the optional time-secfrac portion).
  • The default for image.created involves JS date = new Date() + date.toISOString() which does produce a RFC 3339 timestamp compatible value like 2026-01-27T01:26:03.104Z.

NOTE: Presently labels would set an an empty image.created rather than be filtered out (depends upon: #584).

---

The labels tip I added in the snippet above might only be applicable when not also annotating an image manifest (which would cause it's digest to be modified too, the image manifest has a descriptor to reference the image config digest), which is also the default output for the annotations input (DOCKER_METADATA_ANNOTATIONS_LEVELS).

Image tags are descriptors that AFAIK point to image indexes or direct image manifests (which references image config and individual layers).

• So apart from pushing some redundant changes to image manifests/config and retagging for an otherwise identical image build, beyond some added noise at the registry for untagged digests I guess it's not a concern there
• It could negatively affect downstream users that monitor mutable tag updates with automation to bump their pinned digests (again mostly noise), but as long as image layers remain unmodified (eg: rewritten timestamps via SOURCE_DATE_EPOCH=0 ENV for BuildKit) any pulls of such updates should likewise be light?

org.opencontainers.image.version

org.opencontainers.image.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 priority attribute section (1 + 2 as additional references of users encountering issues due to priority sorting, link 1 provides added clarity on the matter), 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). I've created a feature request for this expression.