Version numbering for Actions

When publishing an Action on the Marketplace, which version numbering scheme should I use?

I am not talking about SemVer, butv1.2.3 vs. 1.2.3 (without the leading v). Also, does GitHub automatically apply SemVer semantics when users refer to use: my/action@v1 and I release v1.0.1, v1.1.0 etc.?


We encourage you to use the leading v.  (For example, our checkout action is actions/checkout@v1.)

We do not currently apply any semantic versioning semantics, we only match a literal release tag.  However we may revisit this policy during the beta period.


That means if I tag v1 and want my users to benefit from bug fixes without having them update their workflow files – I‘d have to move the v1 tag every time?

Also, why use v1 if the tag does not have any meaning at all? I find that’s misleading and suggests something that’s not there yet :man_shrugging:t2:?


I found this confusing/misleading as well. After releasing an action yesterday and tagging the first version as 1.0.0 , I was expecting to be able to use v1 to point to my 1.0.0 version, but was instead getting errors that the action could not be found.

I had read here that in order to use an action, you just need to specify the major version to recieve critical updates and I thought this meant it happens automatically. However I was wrong.

According to this page, what they expect of the action author is that each time a minor version is released, he/she should change the tag corresponding to the major version of that release to point to the new tag, which means that the users of the action will not need to follow minor/patch releases to stay up-to-date.

Move the major version tag (v1, v2, etc.) to point to the Git ref of the current release. For more information, see “Git basics - tagging.”

To automate this, I created the actions-tagger action which does the versioning automatically.

you should use branches (not tags) for major version, e.g. v1 for any 1.x.x version. Apply a fix to v1 branch (and tag with ‘v1.2.3’), then any workflow using uses: action/action@v1 does not need to be updated. You can apply bug/security fixes to branch v1 without rewriting history (e.g. moving tags), and all those workflows would be benefit from it.

Tags are pretty useless, and should only be used for release notes, but unless there are specific reasons, any workflow should point to branches, e.g. uses: action/action@v1, not to tags e.g. uses: action/action@v1.2.3

1 Like