Add a major version ref

[per1234]

As mentioned in the official documentation, it is common practice for the maintainers of GitHub Actions actions to provide a Git ref for each major version series that always points to the latest tag in that series.

For example, for the 1.x.x major version series, a ref named v1 should be created, and moved to the tagged commit at each release (currently https://github.com/codespell-project/actions-codespell/commit/22ff5a2e4b591290baf82d47c9feadac31c65441).

Action dependency version control

There are several possible approaches to controlling the version of an action dependency that will be used in a GitHub Actions workflow

Pin to commit hash

This approach causes the specific version of the action is used by the workflow.

Example:

- uses: codespell-project/actions-codespell@22ff5a2e4b591290baf82d47c9feadac31c65441

This may be appropriate when it is important to ensure an audited version of an action is used for security purposes. However, it also means that the workflow will either require frequent maintenance to keep it up to date, or more likely end up using an outdated version of the action.

Reference branch

This approach causes the version of the action from the current tip of the branch to be used by the workflow.

Example:

- uses: codespell-project/actions-codespell@master

This is appropriate for beta testing, and unavoidable in the case where an action doesn't have releases. However, it is not ideal for use in a production workflow because it subjects it to an unstable version of the action which may introduce bugs or breaking changes at any moment

Major version ref

This approach causes the latest release of the action from within the given major version series to be used by the workflow.

Example:

- uses: codespell-project/actions-codespell@v1

The major version ref offers a balance between the two extremes of the other alternatives by allowing a workflow configuration that will automatically use the latest stable version of the action up to such a time as the major version is bumped due to a breaking change.

Ref options

GitHub Actions supports the use of any Git ref in the jobs.<job_id>.steps[*].uses fields of the workflow. This means there are two options for the creation of a major version ref.

These are functionally identical from the user's perspective, so the choice is a matter of the maintainer's preference or philosophy.

Git tag

This is the most common approach. For example:

• https://github.com/actions/checkout/releases/tag/v3

It is maybe questionable whether it is generally considered best practices to change a Git tag after pushing it to a shared repository, as would be inherent to the nature of a major ref tag. Some discussion about that here.

Branch

Although less common, this is used in some prominent actions. For example:

• https://github.com/octokit/request-action/tree/v2.x
• https://github.com/ruby/setup-ruby/tree/v1

[larsoner]

I created a v1.0 tag, is that good enough?

[peternewman]

Ideally you want a v1 tag too @larsoner then people who want to track v1 (or v1.x.x in semver land or whatever it's called officially in npm) can use that tag, we then need to replace that tag when v1.1 is released etc.

[larsoner]

Feel free to add duplicate tags for that commit @peternewman

[per1234]

Hi @peternewman. I wanted to follow up on this. Please let me know if you have any questions or concerns about creating this tag.

[larsoner]

Done!

https://github.com/codespell-project/actions-codespell/tree/v1

[peternewman]

Thanks @larsoner , sorry I just hadn't got round to it!