There are three ways to use a GitHub action in your projects:
- Use an action that is committed to the same repository that it’s running in
- Point at an external action using the
- 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.
- Create a release using semantic versioning (v1.0.9). For more information, see "Creating releases."
- 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."
- 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
Here's an example after tagging
And here's how it looks once I've tagged
v1.0.1. Notice how the
latest tags now point to the
1.0.1 and not
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
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.