Question: 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?

Answer: 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. Security From a security perspective, using a tag (e.g. @v1 or @v1.1.0) or a branch (e.g. @main) is problematic, because the author of that repository could change where it refers to. A malicious author of an action could add malicious code to that branch or even simply not be careful enough when reviewing a PR and thereby introduce a vulnerability (e.g. via a transitive dependency). By using hashes (e.g. @27b31702a0e7fc50959f5ad993c78deac1bdfc29) you know exactly what you get and it doesn't change unless you choose change the version by updating the hash (at which point you can carefully review the changes). As of early 2022, using hashes instead of tags is not widely adopted, but for example GitHub does this for their docs repository. As supply chain security becomes more important, tools are created to help with "pinning" (point to a specific version by hash rather than tag), such as sethvargo/ratchet. But even depedanbot (see below) should be able to update hashes to the latest hash. 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"