[FIXED] How to know what version of a GitHub Action to use

Issue

I've noticed in various GitHub Action workflow examples, often when calling a pre-defined action (with the uses: syntax) then a particular version of that action is specified. For example:

steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.x'

The above workflow specifies @v2 for both actions/checkout and actions/setup-python.

The question is, how does one know that @v2 is the best version to use?
And how will I know when @v3 becomes available?

Even more confusing is the case of the action used to publish to pypi, pypa/gh-action-pypi-publish. In examples I have looked at, I have seen at least four different versions specified:

• pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
• pypa/gh-action-pypi-publish@master
• pypa/gh-action-pypi-publish@v1
• pypa/gh-action-pypi-publish@release/v1

How do I know which one to use? And in general, how do you know which one's are available, and what the differences are?

Solution

How to know which version to use?

When writing a workflow and including an action, I recommend looking at the Release tab on the GitHub repository. For actions/setup-python, that would be https://github.com/actions/setup-python/releases

On that page, you should see what versions there are and what the latest one is. You want to use the latest version, because that way you can be sure you're not falling behind and upgrading doesn't become too painful in the future.

How to reference a version?

By convention, actions are published with specific tags (e.g. v1.0.1) as well as a major tag (e.g. v1). This allows you to reference an action like so actions/setup-python@v1. As soon as version v1.0.2 is published, you will automatically use that one. This means you profit from bug fixes and new features, but you're prevented from pulling in breaking changes.

However, note that this is only by convention. Not every author of an action publishes a major tag and moves that along as new tags are published. Furthermore, an author might introduce a breaking change without bumping the major version.

When to use other formats

As you said there are other ways you can reference an action such as a specific commit (e.g. actions/setup-python@27b31702a0e7fc50959f5ad993c78deac1bdfc29) and others.

In general, you want to stick to tags as described above. In particular, referencing @main or @master is dangerous, because you'll always get the latest changes, which might break your workflow. If there is an action that advises you to reference their default branch and they don't publish tags, I recommend creating an issue in their GitHub repository asking to publish tags.

Using a git hash can be useful if you need to use a specific version. A use-case could be that you want to test if a specific version would fix a problem or if you see that the author of the action has pushed some new commits with changes that are not tagged yet. You could then test that version of the action.

How to know when there is a new version?

You can use Dependabot for that: Keeping your actions up to date with Dependabot. Dependabot is a tool that creates a pull request in your repository as soon as a new version of any of your actions is available such that you can review what the changes are and keep your workflow up to date.

Here's a sample Dependabot configuration that keeps your actions up to date by creating PRs:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "daily"

Answered By - rethab