Semantic versioning for GitHub Actions

There are three ways to use a GitHub action in your projects:

1. Use an action that is committed to the same repository that it’s running in
2. Point at an external action using the org/repo@branch syntax
3. Point to a tagged docker image

Most people use option 2 - pointing to an external action that’s hosted on GitHub, and the way that most actions recommend that you use them is to point at the master branch so that you’re always up to date.

However, GitHub themselves recommend using semantic versioning for your actions to provide people with a stable experience.

1. Create a release using semantic versioning (v1.0.9). For more information, see "Creating releases."
2. 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."
3. Introduce a new major version tag (v2) for breaking changes that will break existing workflows. For example, changing an action's inputs would be a breaking change.

This is great advice, but it’s is additional effort to update your tag each time you make a new release. This is where the actions-tagger action comes in. It’s a GitHub Action for managing GitHub Actions (how meta!)

Any time you tag a new release in a repository that uses actions-tagger, it will parse the release version, extract the major version from it and redefine that reference.

This means that if you tag version v1.0.0 it will automatically tag v1. Then when you tag v1.0.1, it will change the ref that v1 points to so that it’s the sha from v1.0.1.

Here's an example after tagging v1.0.0:

And here's how it looks once I've tagged v1.0.1. Notice how the v1 and latest tags now point to the sha for 1.0.1 and not 1.0.0?

Your consumers of your action can point at v1 safe in the knowledge that they’ll continue to get action updates without any breaking changes. If you need to make breaking changes, tag v2.0.0 and those that need to upgrade can upgrade. Everyone else can continue using v1.

If we followed the common advice of using @master as the version, everyone’s workflows would break as soon as you pushed your breaking changes. Using actions-tagger we can have all of the benefits of auto-updating actions without any of the risks.