Proposal: Generate metadata from Git ref and CIs events

This proposal aims to make tags and labels generation transparent the same way as metadata-action but handled directly in the CLI for build/bake commands through new flags:

• --meta-image stringArray: List of Docker images to use as base name for tags (e.g. moby/buildkit)
• --meta-tag stringArray: List of options for tag
• --meta-flavor stringArray: Flavor to apply
• --meta-oci bool: Generate OCI Image Format Specification labels

Another possibility would be to extend --tag flag to handle that or only be able to use it through bake to avoid many flags.

We can create a separate library (or not) that aims to extract Git metadata object and CI providers metadata such as GitHub Actions, Travis CI, CircleCI, Jenkins, and so on. Git metadata would be used as fallback if no CI provider is found. Flags values would then be passed to this library.

--meta-tag

To generate metadata according to user needs, several type could be used as key-value pair attributes:

--meta-tag=

If --meta-tag is defined but empty, the following entries will used:

• --meta-tag=type=schedule
• --meta-tag=type=ref,event=branch
• --meta-tag=type=ref,event=tag
• --meta-tag=type=ref,event=pr

--meta-tag=type=schedule

• minimal: --meta-tag=type=schedule
• default: --meta-tag=type=schedule,pattern=nightly
• template: --meta-tag=type=schedule,pattern={{ date 'YYYYMMDD' }}

Will be used on schedule event for some CI providers that can handle it like TravisCI and GitHub Actions.

pattern is a specially crafted attribute that would support Go template with the following expressions:

• date 'format' ; render date

Pattern	Output
nightly	nightly
{{ date 'YYYYMMDD' }}	20210813

--meta-tag=type=semver

• minimal: --meta-tag=type=semver,pattern={{ .Version }}
• use custom value instead of git tag: --meta-tag=type=semver,pattern={{ .Version }},value=v1.0.0

Will be used on a push tag event and requires a valid semver Git tag, but you can also use a custom value through value attribute.

pattern attribute supports Go template with the following expressions:

• raw ; the actual tag
• version ; shorthand for {{ .Major }}.{{ .Minor }}.{{ .Patch }} (can include pre-release)
• major ; major version identifier
• minor ; minor version identifier
• patch ; patch version identifier

Git tag	Pattern	Output
v1.2.3	{{ .Raw }}	v1.2.3
v1.2.3	{{ .Version }}	1.2.3
v1.2.3	{{ .Major}}.{{ .Minor }}	1.2
v1.2.3	v{{ .Major }}	v1
v1.2.3	{{ .Minor }}	2
v1.2.3	{{ .Patch }}	3
v2.0.8-beta.67	{{ .Raw }}	2.0.8-beta.67*
v2.0.8-beta.67	{{ .Version }}	2.0.8-beta.67
v2.0.8-beta.67	{{ .Major }}.{{ .Minor }}	2.0.8-beta.67*

*Pre-release (rc, beta, alpha) will only extend {{ .Version }} as tag because they are updated frequently,
and contain many breaking changes that are (by the author's design) not yet fit for public consumption.

--meta-tag=type=ref

• branch event: --meta-tag=type=ref,event=branch
• tag event: --meta-tag=type=ref,event=tag
• pull request event: --meta-tag=type=ref,event=pr

This type handles Git ref for the following events:

• branch ; eg. refs/heads/master
• tag ; eg. refs/tags/v1.0.0
• pr ; eg. refs/pull/318/merge

Event	Ref	Output
pull_request	refs/pull/2/merge	pr-2
push	refs/heads/master	master
push	refs/heads/my/branch	my-branch
push tag	refs/tags/v1.2.3	v1.2.3
push tag	refs/tags/v2.0.8-beta.67	v2.0.8-beta.67

--meta-tag=type=sha

• minimal (short sha): --meta-tag=type=sha
• full length sha: --meta-tag=type=sha,format=long

Output Git short commit (or long if specified) as Docker tag like sha-ad132f5.

--meta-flavor

--meta-flavor defines a global behavior for --meta-tag:

• --meta-flavor=latest=<auto|true|false>: Handle latest tag (default auto)
• --meta-flavor=prefix=<string>,onlatest=<true|false>: A global prefix for each generated tag and optionally for latest
• --meta-flavor=suffix=<string>,onlatest=<true|false>: A global suffix for each generated tag and optionally for latest

latest tag will be generated by default (auto mode) for:

• --meta-tag=type=ref,event=tag
• --meta-tag=type=semver,pattern=...

--meta-oci

Generate OCI Image Format Specification labels:

{
    "org.opencontainers.image.title": "Hello-World",
    "org.opencontainers.image.description": "This your first repo!",
    "org.opencontainers.image.url": "https://github.com/octocat/Hello-World",
    "org.opencontainers.image.source": "https://github.com/octocat/Hello-World",
    "org.opencontainers.image.version": "1.2.3",
    "org.opencontainers.image.created": "2020-01-10T00:30:00.000Z",
    "org.opencontainers.image.revision": "90dd6032fac8bda1b6c4436a2e65de27961ed071",
    "org.opencontainers.image.licenses": "MIT"
}

If some are not suitable, user can overwrite them with the --label flag.

cc @tonistiigi @thaJeztah @chris-crone

Start by reviewing the build and bake command entry points and the linked metadata-action behavior. The proposal does not name implementation files or tests; completion would require an agreed design for Git and CI metadata extraction, the proposed metadata flags, generated tags, and OCI labels.