Enable Flag in Raw Tag does not work as expected

[baxterjo]

Contributing guidelines

• I've read the contributing guidelines and wholeheartedly agree

I've found a bug, and:

• The documentation does not mention anything about my problem
• There are no open or closed issues that are related to my problem

Description

When using a raw tag with the enable flag, the tag is still in the metadata output when enable is set to false.

Expected behaviour

Run docker/metadata-action@v5
Context info
Processing images input
Processing tags input
  type=semver,pattern={{raw}},value=v0.0.1+test,enable=true,priority=900
  type=raw,value=latest,enable=false,priority=200
Processing flavor input
Docker image version
Docker tags
  ghcr.io/{org}/{image}:v0.0.1-test
Docker labels
Annotations
JSON output
Bake file definition (tags)
Bake file definition (labels)
Bake file definition (annotations)

Actual behaviour

Run docker/metadata-action@v5
Context info
Processing images input
Processing tags input
  type=semver,pattern={{raw}},value=v0.0.1+test,enable=true,priority=900
  type=raw,value=latest,enable=false,priority=200
Processing flavor input
Docker image version
Docker tags
  ghcr.io/{org}/{image}:v0.0.1-test
  ghcr.io/{org}/{image}:latest
Docker labels
Annotations
JSON output
Bake file definition (tags)
Bake file definition (labels)
Bake file definition (annotations)

Repository URL

No response

Workflow run URL

No response

YAML workflow

- name: Docker Meta
  id: meta
  uses: docker/metadata-action@v5
  with:
    images: ${{ needs.set-workflow-vars.outputs.image-name }}
    tags: |
      type=semver,pattern={{raw}},value=${{ needs.set-workflow-vars.outputs.version }}
      type=raw,value=latest,enable=${{ inputs.is-latest }} # This input is typed as a boolean in the callable workflow, maybe that's it?

Workflow logs

Run docker/metadata-action@v5
Context info
Processing images input
Processing tags input
  type=semver,pattern={{raw}},value=v0.0.1+test,enable=true,priority=900
  type=raw,value=latest,enable=false,priority=200
Processing flavor input
Docker image version
Docker tags
  ghcr.io/{org}/{image}:v0.0.1-test
  ghcr.io/{org}/{image}:latest
Docker labels
Annotations
JSON output
Bake file definition (tags)
Bake file definition (labels)
Bake file definition (annotations)

BuildKit logs

No response

Additional info

No response

[crazy-max]

type=raw,value=latest,enable=${{ inputs.is-latest }}

Do you repro as well with type=raw,value=latest,enable=false? If not then that might be related to how GitHub handles boolean inputs.

[baxterjo]

type=raw,value=latest,enable=${{ inputs.is-latest }}

Do you repro as well with type=raw,value=latest,enable=false? If not then that might be related to how GitHub handles boolean inputs.

Yea that question is in the comment of the line where the bug originates from. It is a GHA typed boolean for sure. The peculiar thing is the fix I ended up going with.

Intsead of

- name: Docker Meta
  id: meta
  uses: docker/metadata-action@v5
  with:
    images: ${{ needs.set-workflow-vars.outputs.image-name }}
    tags: |
      type=semver,pattern={{raw}},value=${{ needs.set-workflow-vars.outputs.version }}
      type=raw,value=latest,enable=${{ inputs.is-latest }} # This input is typed as a boolean in the callable workflow, maybe that's it?

I ended up using the flavor input. Which is documented the same as tags as far as booleans go:

- name: Docker Meta
   id: meta
   uses: docker/metadata-action@v5
   with:
     images: ${{ steps.set-vars.outputs.image-name }}
     flavor: |
       latest=${{ inputs.is-latest }}
     tags: |
       type=semver,pattern={{raw}},value=${{ inputs.version }}

[polarathene]

Looks like this happened because you previously had the auto flavor paired with your semver type tag trigger:

metadata-action/src/meta.ts

Lines 171 to 186 in 8e1d546

	let latest = false;
	const sver = semver.parse(vraw, {
	loose: true
	});
	if (semver.prerelease(vraw)) {
	if (Meta.isRawStatement(tag.attrs['pattern'])) {
	vraw = this.setValue(handlebars.compile(tag.attrs['pattern'])(sver), tag);
	} else {
	vraw = this.setValue(handlebars.compile('{{version}}')(sver), tag);
	}
	} else {
	vraw = this.setValue(handlebars.compile(tag.attrs['pattern'])(sver), tag);
	latest = true;
	}
	return Meta.setVersion(version, vraw, this.flavor.latest == 'auto' ? latest : this.flavor.latest == 'true');

1. At the start of that snippet the latest variable is initially false and if the semver tag being processed is considered a release tag (not parsed as a semver pre-release version) it'll be set to latest=true.
2. Finally at the end of that snippet it'll check flavor.latest, which if configured as auto will use the latest variable (release: true, or for pre-release: false) that was set in the prior condition, otherwise it'll use what was explicitly configured on the workflow (flavor.latest=<true|false>).

That's why your workaround to configure instead with flavor.latest worked 😎

It's a subtle bug that the README should probably highlight better, enable=false skips the tag processing, but for the latest tag itself you have to keep the default flavor behaviour in mind.

---

Additional context

Earlier in the process that semver type was processed here:

metadata-action/src/meta.ts

Lines 46 to 61 in 8e1d546

	private getVersion(): Version {
	let version: Version = {
	main: undefined,
	partial: [],
	latest: undefined
	};
	for (const tag of this.tags) {
	const enabled = this.setGlobalExp(tag.attrs['enable']);
	if (!['true', 'false'].includes(enabled)) {
	throw new Error(`Invalid value for enable attribute: ${enabled}`);
	}
	if (!/true/i.test(enabled)) {
	continue;
	}
	switch (tag.type) {

metadata-action/src/meta.ts

Lines 66 to 69 in 8e1d546

	case tcl.Type.Semver: {
	version = this.procSemver(version, tag);
	break;
	}

So the raw tag was in fact skipped due to your enabled=false, the caveat is latest was implicitly added regardless due to flavor.latest=auto + semver, which due to priority is processed first (even if priority was adjusted though, the enabled=false would skip setting version.latest=false, so you'd still get version.latest=true set once the semver tag is processed).

Tags are iterated through an array based on their priority:

metadata-action/src/tag.ts

Lines 43 to 52 in 8e1d546

	export const DefaultPriorities: Record<Type, string> = {
	[Type.Schedule]: '1000',
	[Type.Semver]: '900',
	[Type.Pep440]: '900',
	[Type.Match]: '800',
	[Type.Edge]: '700',
	[Type.Ref]: '600',
	[Type.Raw]: '200',
	[Type.Sha]: '100'
	};

If the raw tag had a higher priority (and was enabled) it'd have precedence at setting the latest tag to false:

metadata-action/src/meta.ts

Lines 314 to 317 in 8e1d546

	private procRaw(version: Version, tag: tcl.Tag): Version {
	const vraw = this.setValue(this.setGlobalExp(tag.attrs['value']), tag);
	return Meta.setVersion(version, vraw, this.flavor.latest == 'auto' ? false : this.flavor.latest == 'true');
	}

latest is decided by the first tag to set it when it's in an undefined state:

metadata-action/src/meta.ts

Line 333 in 8e1d546

private static setVersion(version: Version, val: string, latest: boolean): Version {

metadata-action/src/meta.ts

Lines 343 to 345 in 8e1d546

	if (version.latest == undefined) {
	version.latest = latest;
	}

---

Comparison in source (not relevant)

latest:

metadata-action/src/flavor.ts

Lines 4 to 5 in 8e1d546

	export interface Flavor {
	latest: string;

metadata-action/src/flavor.ts

Lines 37 to 42 in 8e1d546

	switch (key) {
	case 'latest': {
	flavor.latest = value;
	if (!['auto', 'true', 'false'].includes(flavor.latest)) {
	throw new Error(`Invalid latest flavor entry: ${input}`);
	}

---

enable:

metadata-action/src/tag.ts

Lines 88 to 99 in 8e1d546

	export function Parse(s: string): Tag {
	const fields = parse(s, {
	relaxColumnCount: true,
	skipEmptyLines: true
	})[0];
	const tag = new Tag();
	for (const field of fields) {
	const parts = field
	.toString()
	.split(/(?<=^[^=]+?)=/)
	.map(item => item.trim());

metadata-action/src/tag.ts

Line 1 in 8e1d546

import {parse} from 'csv-parse/sync';

metadata-action/src/tag.ts

Lines 203 to 205 in 8e1d546

	if (!Object.prototype.hasOwnProperty.call(tag.attrs, 'enable')) {
	tag.attrs['enable'] = 'true';
	}

metadata-action/src/meta.ts

Lines 53 to 60 in 8e1d546

	for (const tag of this.tags) {
	const enabled = this.setGlobalExp(tag.attrs['enable']);
	if (!['true', 'false'].includes(enabled)) {
	throw new Error(`Invalid value for enable attribute: ${enabled}`);
	}
	if (!/true/i.test(enabled)) {
	continue;
	}

[baxterjo]

It's a subtle bug that the README should probably highlight better

I think a louder warning or an action failure when processing special case tags would better. Something that points to a corresponding readme section.

[polarathene]

Just to clarify, you specifically mean with type=raw,value=latest,enable=false caveat with the default flavor.latest=auto?

I think there's other tag rules that could run into that latest tag issue depending on the setup, but the logic is a tad messy to sift through 😓 This is the most common combination I've seen though where the mishap happens.

[baxterjo]

Yea I think any tags that can be listed in the tags section whose behavior can be influenced by another setting should come with a warning if there are conflicting settings. I think just a quick lint or sanity check before attempting to run the action would be sufficient. I realize teasing out the edge cases could be tough, but the amount of time saved for devs would be worth it IMO. The iteration loop for CI jobs is loooooong, so being able to tighten up the feedback pays off in dividends.

[baxterjo]

I'm ultimately apathetic about it though as I rarely work on CI these days. Feel free to close this if you don't want to use it as a tracking issue.

[polarathene]

I'm short on time, so here's a rough outline for anyone landing here, that may want to contribute a fix to the README:

• type=raw could mention a caveat with value=latest.
• The latest tag section references the default flavor.latest=auto behaviour.
  • That section then suggests using a type=raw tag with enable for controlling a conditional latest tag, without clarifying that the flavor.latest=auto default will disregard/override that enable logic.
  • Additionally if flavor.latest=true and a type=raw,value=latest,enable=true tag are both present, the tags output will produce two latest tags (even when there is no suffix/prefix difference involved).
• flavor setting describes the onlatest condition for flavor.<prefix|suffix>:

  • It is not clarified that onlatest attribute is only applicable to an implicit latest tag generated from flavor.latest=<auto|true> (when auto resolves to true). onlatest has no relation to an explicit type=raw,value=latest tag (which could easily be confused that it does).

  • onlatest is also false by default, but that's not documented either (see this recent bug report from a confused user).

  • flavor.suffix (and equivalent flavor.prefix) applies to all explicit tags, but can also be used as an attribute in tags to opt-out via ,suffix= (suffix unset via an empty value). This override behaviour could be documented more clearly, given the current docs that show a tag types implicit defaults which already include ,prefix=,suffix= it may not be obvious that you can opt-out of the flavor prefix/suffix this way.

    metadata-action/README.md

    Lines 703 to 708 in 318604b

    	Extended attributes and default values:
    	```yaml
    	tags: |
    	type=raw,enable=true,priority=200,prefix=,suffix=,value=
    	```