Unstable GitHub Ref
Creating predictable and stable execution environments is critical in order to get reliable, consistent and reproducible results. External Actions are frequently used, and when implementing them in a workflow, you can reference any other GitHub repository. The format of this reference is important to ensuring that the content you are using is not changing often in order to provide reproducible builds.
Best Practice
The best practice that's recommended by this check is to include other repositories using references that will not change unexpectedly. GitHub Actions can be used by using a Commit SHA, a Tag or a Branch.
Commit SHAs
When referencing a GitHub Action by a Commit SHA, you are guaranteed that time your workflow executes, it will use the same version of the Action. Note: An action by have external dependencies of it's own that could change over time. Referencing an Action by Commit SHA is the safest way to include an Action in your workflow. When you use a Commit SHA, you will never receive unexpected updates, so you will then be responsible for updating when there's a new version available. When using Proaction, the outdated action will detect when there's a newer Commit SHA available and suggest updates.
Tags
Tags are, by definition, immutable. A tag is created in GitHub to point to a Commit SHA, and this can never change. This is easier to understand than long Commit SHAs and most importantly, sortable. Tags are often Semver, so it's easy to know when there's a newer version available without using automated tools. The risk with tags is that while they cannot be updated to point to a new Commit SHA, they can be deleted and recreated. A GitHub Tag is not guaranteed to point to the same Commit SHA each day because the developer may delete and recreate it. Proaction will help provide updates to GitHub Tags if you are using one. In addition, Proaction will track what Commit SHA a Tag points to, and when it's changed, it will record it as an unstable tag. If you are using tag that's known to be unstable, Proaction will recommend that you move to a Commit SHA for stability. Because many developers use Tags to ship their versions, Proaction maintains a list of Tags are are recommended. If you are an Action developer and want to provide your recommended Tags to Proaction, we maintain a list of GitHub refs that you can edit.
Special Case For Semver Tags
Semver is a popular tagging convention where a tag is created as major.minor.patch.
While Proaction recommends choosing the most predictable and stable tag, if a workflow is discovered that uses a version only specifying a Major version (i.e. v2) when there is a more specific Semver tag available (i.e. v2.0.1), it will recommend that you move to the more specific tag.
For example, if you are referencing v1 and there's a v1.0.1 and a v1.0.2 Tag, Proaction will recommend updating to v1.0.2 because it is more specific and more reliable.
Again, the the outdated action will detect new minor versions and suggest updates.
Branches
Actions that reference a Branch are the most unstable and unpredictable. New commits can be merged in at any tirecommentme, and a Branch offers no immutability protection. Proaction does not recommend using Branches and will always recommend moving to a Tag or a Commit SHA if a Branch is found in a workflow.
Local References
Workflows that reference Actions using a local, relative file path will not create this issue because these are automatically versioned with the workflow.
Configuration
This Proaction is enabled by default. It can be disabled on the organization or repository settings.
| Setting | Default | Description |
|---|---|---|
| Allow Semver Tags | false | When true, no issues will be created for workflow runs that use well-defined semver tags |
Troubleshooting
Why am I getting this issue when following the recommendations from the Action developer?
Action developers build their docs to help you stay updated with the latest functionality and fixes. This means that many developers suggest using the master or a semver tag in their examples. Switching the commit sha will not break your workflow that uses the action, but it makes your environment more reliable.
I received an issue for a workflow that hasn't changed for a long time
Proaction will monitor GitHub tags that your workflows reference. While these can be stable and reference the same release for a long time, the risk is that that a tag can be overwritten on GitHub. When this happens, Proaction will create an issue, even if your workflow has not recently executed or changed. In addition, Proaction has data collected from many actions, including how stable their tags have been. This data is available to all workflows monitored by Proaction.