metadata-action Strip the prefix `v` from tags created on release event

          Following-up on this, I am finding that on the release published event the `v` from the tag version is not being stripped from the `{{version}}` variable. This seems incorrect, if the action is supposed to work correctly also on that event type.

          Is this something that was done by design, or instead something that could get updated to match (partially, I agree with the caveats regarding pre-releases) the behaviour on the tag push event?

Originally posted by @esune in https://github.com/docker/metadata-action/issues/240#issuecomment-1578947442

I realize that this still occurs, and the generated tags contain the v prefix.

Jun 14 '24 12:06 Nosfistis

TL;DR: Everything is working correctly as documented. You have misconfigured.

Worth noting from the issue you referenced (and the one it references), there is acknowledgement that there is no release event support on this actions docs. It's only "supported" in the sense that the event itself results in the refs/tags/<your tag> event metadata, which if you have a compatible tag rule to match on that it'll be used.

The v stripping only occurs during the type=semver,pattern= tag rule:

https://github.com/docker/metadata-action/blob/8e1d5461f02b7886d3c1a774bfbd873650445aa2/src/meta.ts#L172-L184

NOTE: It's technically discouraged since SemVer 2.0.0 to prefix with v (but IIRC this is still expected for Go tooling, and this action supports the convention implicitly through the semver package):

A leading "=" or "v" character is stripped off and ignored. Support for stripping a leading "v" is kept for compatibility with v1.0.0 of the SemVer specification but should not be used anymore. Source

Using the release event type to trigger does set GITHUB_REF to /refs/tags/<your tag> which is required for this semver tag type:

https://github.com/docker/metadata-action/blob/8e1d5461f02b7886d3c1a774bfbd873650445aa2/src/meta.ts#L155-L158

But if you have other tag rules like in the referenced issue:

tags: |
  type=ref,event=branch
  type=ref,event=tag

That calls different methods to process what tags to generate:

https://github.com/docker/metadata-action/blob/8e1d5461f02b7886d3c1a774bfbd873650445aa2/src/meta.ts#L78-L87

https://github.com/docker/metadata-action/blob/8e1d5461f02b7886d3c1a774bfbd873650445aa2/src/meta.ts#L272-L286

As you can see the event=tag will trigger that which just publishes the tag as-is. No v would be stripped then.

You should be able to use either of the on.release or on.push.tags event triggers since all that matters here is the /ref/tags/<your tag> part of the event, and matching that to the appropriate tag rule.

As shown earlier, there are only three event types actually supported for type=ref:

https://github.com/docker/metadata-action/blob/8e1d5461f02b7886d3c1a774bfbd873650445aa2/src/tag.ts#L15-L19

Thus there is no type=ref,event=release, and neither you nor the comment you referenced shared what tags you configured for the action. You likely either had none and relied upon defaults (which are documented as not stripping the v prefix), or you copy/pasted the tags config from somewhere without understanding them properly.

Feb 25 '25 21:02 polarathene

Left a comment on the original issue as well: https://github.com/docker/metadata-action/issues/240#issuecomment-2685800770

It's been a while now, but I believe the issue I was having turned out to be ONLY when creating a pre-release from a tag (i.e.: flagging the release as pre-release in GitHub). Creating official/latest releases seems to work as expected now. I am not sure why pre-releases would behave differently for prefixes though.

Feb 26 '25 18:02 esune

I am not sure why pre-releases would behave differently for prefixes though.

https://github.com/docker/metadata-action/blob/902fa8ec7d6ecbf8d84d538b9b233a880e428804/src/meta.ts#L156-L169

https://github.com/docker/metadata-action/blob/8e1d5461f02b7886d3c1a774bfbd873650445aa2/src/meta.ts#L171-L184

loose: Be more forgiving about not-quite-valid semver strings. (Any resulting output will always be 100% strict compliant, of course.) For backwards compatibility reasons, if the options argument is a boolean value instead of an object, it is interpreted to be the loose param.

Strict-mode Comparators and Ranges will be strict about the SemVer strings that they parse.

valid(v): Return the parsed version, or null if it's not valid.

major(v): Return the major version number.

minor(v): Return the minor version number.

patch(v): Return the patch version number.

parse(v): Attempt to parse a string as a semantic version, returning either a SemVer object or null.

Source (semver NPM docs)

That first snippet I reference calls semver.valid(), which if done so as strict-mode presumably emits that warning for pre-release with v? Otherwise if it's not occurring there, we have that 2nd snippet which has a pre-release conditional branch..

Looks like it'd probably get treated the same as a non-prerelease, although I'm not sure where {{version}} is handled, as those semver docs don't mention a version() function. From what I can see handlebars receives the template to generate the tag string from, and it's given sver as an object with functions on it to call from the template string.

If the v prefix stripping occurs somewhere else, I'm not quite sure where 🤔 I assume it's reliant upon semver package, so if that doesn't support stripping away the v prefix, the bug fix would either be handled up there or some additional config option for using semver in the referenced snippets above.

Feb 26 '25 21:02 polarathene

For reference the README type=semver section does suggest that the v prefix should be stripped:

You likely had a misconfiguration that used the raw tag then? Or another rule like the reporter here likely had with a type=ref,event=tag?

Someone would need to reproduce and share actual workflow config and run if it's happening with only type=semver 🤔

Feb 26 '25 21:02 polarathene

I am pretty positive I was using type=semver,pattern={{version}} and type=semver,pattern={{major}}.{{minor}} in my action. There also is type=ref,event=pr as the tagging happens inside of a build action that is reused in a couple workflows, and the tags might be different based on that (see here if curious).

I would have to test again and see if the issue persists and what is it exactly, might do it as an experiment next time we need to publish a release by going through a pre-release first).

Feb 26 '25 21:02 esune

There also is type=ref,event=pr as the tagging happens inside of a build action that is reused in a couple workflows, and the tags might be different based on that (see here if curious).

I went through the tag history of that repo, were these your pre-release style tags in question?:

Because they were published without a v prefix:

I would have to test again and see if the issue persists and what is it exactly, might do it as an experiment next time we need to publish a release by going through a pre-release first).

Nothing stood out from the other two tag types when I went over the docker/metadata-action source, and without a reproduction of it in the wild to reference I'd have to attempt to reproduce myself instead of trying to drive-by assist 😝

If you do encounter it again, a more minimal workflow to reproduce may also be worthwhile context to confirm it's not due to a more complex interaction.

Off-topic: Out of curiousity, are you getting any known value from using type=sha / ~~type=ref,event=pr~~ (EDIT: This one I understand)?

I don't see much point in the sha tags personally:

Does anyone actually use those tags for your images to reference past images? Generally you'd use an explicit tag and if that tag is prone to being re-assigned you may instead pin by digest at the time.
It's messy to browse past images that no longer serve a purpose when they're still in the tagged images list 🤷‍♂ (I'm assuming you chose to do so on the whim that it might be useful before you ever actually had a need for it?)

Ignore (resolved)

Same with the PR tagging. Not sure if you're aware but secrets on PR triggered workflow runs are not available (unless using something like pull_request_target event and trusting the PR itself cannot exploit access to secrets that way). IIRC that may not apply to branches on your own repo that PR to another branch, but that doesn't make the feature too useful consistency wise when it comes to third-party contributors. I mention this due to stuff like this which is referencing secrets.

EDIT: Workflow run for PR on local repo branch. I see you're actually deploying the PR images with a purpose and a conditional to ensure it's only on local branches with a cleanup step (I was wondering why I didn't see many pr tagged images 😅)

Feb 27 '25 01:02 polarathene

@polarathene honestly at this point I don't recall anymore, it's been too long 😅

For the sha tag: we use the short sha to deploy to our dev environment and know which image is there at any given time, as it is the target of our CI/CD pipeline. I agree all of those sha tags though make the artifact repository messy: it is something that was inherited and we never managed to fully clean-up, we had an action that was supposed to clean up old/unused images (snok/container-retention-policy), but after an update it started deleting more than it needed to and we had to turn it off

Feb 27 '25 17:02 esune