Best Practices
Maintainable Workflows
Workflows can become complex documents that are not often updated. A good workflow may run for a long time before it needs any attention. A well-built workflow will need less maintenance because it's routinely updated to mitigate the problems that may be caused by neglect. Sometime Actions deprecate functionality over time, and keeping a workflow updated will minimize the work needed and also allow you to schedule the work when it's convienent for you. A neglected workflow may work for a while, and then break unexpectedly when an Action is no longer available or finally deletes a deprecated change.
Reproducible Workflows
Having reproducible workflows is important in order to ensure that each execution is both reliable and deterministic. A workflow is reproducible when the following statement is true about execution: Multiple executions from the same workflow and the same commit must be guaranteed to produce the exact same result
Reliability
If a workflow is not reproducible, it's not a reliable workflow. Most workflows rely on external dependencies, and a workflow should not fail if an external dependency is updated. It's possible to build most workflows to not be susceptible to changing external dependencies, and this is one step that helps prevent developers from being distracted by the urgency of a failing workflow and the need to update because it's blocking other work.
Security
If a workflow is dependent on external resources, but each execution might produce a different result, then the output of the workflow should not be trusted. If a workflow execution is deterministic and non-deterministic execution is unexpected, then the workflow will not be susceptible to external tampering and changes.
Up To Date Workflows
Keeping workflows updated means you have access to bug fixes, security fixes and other recommended or required updates. Proaction will find the latest version of Actions and will recommend changes to update a workflow to use the latest version.
Available Proaction Checks
The problems presented on this page are mitigated by the following Proaction checks:
- outdated action
- unstable github ref
Commits, Tags and Branches
GitHub actions are often consumed from other repos. When referencing a repo to use, the syntax is:
Where reference is either a branch, tag or a commit hash. The different options available here allow you to control who has access to update the version of the Action used by your workflow.
Branch
When you reference a branch (e.g. master), the Action developer can push any changes and your next workflow execution will use their latest version. This can introduce bugs, breaking changes, and even possibly security vulnerabilities. Referencing a branch is not recommended. The unstable github ref check will recommend moving any workflows that use branches to instead use commit shas, and let the outdated check give you control to update the workflow.
Tag
When you reference a tag (e.g. v1), the Action developer has made a release that is labeled and should not be changed. Tags are immutable objects in GitHub, but they can be deleted and recreated. Tags are a good way to reference known, human readable, visually distinct versions that should not change. Just remember that tags can change and you still risk unpredictible workflow executions because the Action developer has some control over the update policy. The unstable github ref check will recommend changing some workflows that use branches to use commit shas instead, and let the outdated check give you control to update the workflow. There are exceptions here, and the check knows if a tag has a stable history or not.
Commit
When you reference a commit hash (e.g. abc123d), this is guaranteed to be immutable. The Action developer can delete this commit (or the repo) but it's impossible for the commit hash to point to a new version of the action. Using this is the most stable way to create reproducible workflows. The outdated check is designed to keep your commit-hash based workflows updated to the latest version.