Versioning guidance for authoring and consuming actions

What really puzzles me is that on any GitHub action web page (in the Marketplace), when you click “Use latest version”, the YAMLsnippet is presenting you something like:

uses: actions/name@v1.2.3

where a specific tag is being used.

Instead, in my experience, it is best to:

  • action’s author should publish branches that contains major version of the action (e.g. branch v1 for any v1.x.x version, branch v2 for any v2.x.x.
  • action’s consumer should consume those branches, e.g. uses: action/action@v2.

This allows author to push bugs/security fixes to the branch v1 (and tag it for the release note purpose only) so that any workflow referring to the action on branch v1 (e.g. uses: action/action@v1) would automatically benefit of the fix, without requiring any update. It is the concept of servicing a major version of the action.

Is this rule documented somewhere? I see that samples correctly adhere to this best practice, but the Marketplace is really misleading to this respect.

Action consumers should be strongly suggested to specify a branch name in place of a specific tag instead.

Here are some excerpts from the docs:

We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag number. If you don’t specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.

  • Using the commit SHA of a released action version is the safest for stability and security.
  • Using the specific major action version allows you to receive critical fixes and security patches while still maintaining compatibility. It also assures that your workflow should still work.
  • Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

As not all action authors follow semantic versioning, it’s reasonable to default to @1.2.3 to ensure that your automation doesn’t break should they push an a breaking update without bumping the major version number.

The creators of a community action have the option to use tags, branches, or SHA values to manage releases of the action. Similar to any dependency, you should indicate the version of the action you’d like to use based on your comfort with automatically accepting updates to the action.

You can opt-in to use more recent versions of an action by specifying @1.2 or @1 only.

Create a release using semantic versioning [as author of an action]. For more information, see “Creating releases.”

Following SemVer will allow users of an action to specify just the major version like @v2 to use the latest 2.x.x version, without having to fear breaking changes.

Pin actions to a full length commit SHA [for security]

This allows you to audit the third-party code and use the exact version you reviewed. Otherwise the third party could replace an existing version 1.2.3 with malicious code without you noticing.

What you provided makes sense, although it is too vague in several points and it is not explicitly explained what authors and consumer of GitHub action should do.

For example:

it’s reasonable to default to @1.2.3 to ensure that your automation doesn’t break

What is “1.2.3” ? If it is a git ref, it can always be moved and break your automation.

You can opt-in to use more recent versions of an action by specifying @1.2 or @1 only.

If the workflow specifies: uses: action/name@1.2, will it match any of the following?

  • @1.2.10
  • @1.2.3
  • @1

If does not match any, this is not explicitly stated in the docs, and it is not true it will use the most recent version.
Instead it will just fail saying that such ref 1.2 has not been found.

Following SemVer will allow users of an action to specify just the major version like @v2 to use the latest 2.x.x version, without having to fear breaking changes.

This again is not true. If the action has been released with Git tags v2.0.0, v2.0.1, v2.1.0 (following SemVer versioning), none of those will match the @v2, as the match on the ref is satisfied on identity.

Pin actions to a full length commit SHA [for security]

This makes little sense: if you do not want to take any risk you should not use any GitHub action. There is simply no way you could establish if a given ref in a repository is safe for you. You ought to check the action and all its dependencies (and external dependencies as well, as webservice endpoints).

In summary, the documentation for GitHub action authors should explicitly say:

  • publish major version as a branch can call it as v1, v2 (not tags, because branch are meant to be moved, e.g. on subsequent updates/fixes of major version v2);
  • publish a tag for minor and patches, e.g. v1.1.1, v1.2.0 (not branch, but does not really matter); this is useful for release notes, and yes, someone would like to pin the workflow that version for any reason.

The documentation for GitHub action consumers should explicitly suggest:

  • uses: action/name@v1 to use latest version on major version v1.
    explaining that this way the workflow does not need to be updated on subsequent bug/security fixes.