Skip to main content
Ensure stable and predictable execution of your GitHub workflows by versioning your custom actions. In this guide, we’ll cover three methods to specify exact action releases: tags, branches, and commit SHAs.

​
1. Versioning with Tags

Tags are the most common approach to label and organize GitHub Action releases. They support both flexible version ranges and precise version pins.
Tag TypePurposeExample
Major versionSignificant or breaking changesuses: actions/checkout@v3
Pre-release (beta)Beta releases for testing before GAuses: actions/checkout@v3-beta
Semantic versioningPrecise MAJOR.MINOR.PATCH tagsuses: actions/[email protected]
steps:
  - uses: actions/checkout@v3        # Major version
  - uses: actions/checkout@v3-beta   # Beta release
  - uses: actions/[email protected]    # Semantic versioning
Using Semantic Versioning ensures clear communication of changes and consistent release management.

​
2. Referencing a Branch

Referencing a branch name (e.g., main or master) always pulls the latest action code from that branch. While convenient for continuous updates, this approach can introduce unexpected breaking changes. 
steps:
  - uses: actions/checkout@main      # Always uses the latest code on 'main'
Pinning to a branch like main can lead to non-deterministic builds if the branch receives breaking changes.

​
3. Pinning to a Commit SHA

Commit SHAs guarantee immutability by referencing a specific commit. This is the most reliable method for ensuring your workflow uses exactly the code you intend. 
steps:
  - uses: actions/checkout@a8240080885750b8e136effc585c3cd6082bd575f  # Specific commit SHA
Commit SHAs are tamper-proof and cannot be moved or deleted, providing maximum stability.

​
Summary

Choosing the right versioning strategy depends on your needs:
  • Tags: Best balance between flexibility and stability.
  • Branches: Ideal for continuous updates, but risk instability.
  • Commit SHAs: Maximum reliability with immutable references.

Watch Video