6.1 Action Versioning, Semantic Releases & Tagging

Action Versioning, Semantic Releases & Tagging

When authoring and distributing custom GitHub Actions—whether for internal enterprise consumption or the public GitHub Marketplace—establishing a robust release and versioning strategy is essential. Workflows consuming your actions depend on predictable behavior, non-breaking updates, and cryptographic integrity.

Understanding how GitHub Actions resolves Git references (@v1, @v1.2.3, @main, @<commit-sha>) and mastering release automation patterns is a core competency tested on the GitHub Actions Certification (GH-200) examination.

---

1. Semantic Versioning (SemVer 2.0.0) in Actions

GitHub Actions strongly recommends that action authors adhere to Semantic Versioning 2.0.0 (vMAJOR.MINOR.PATCH). Each segment communicates specific compatibility guarantees to consuming workflows:

   v 1 . 4 . 2
     │   │   │
     │   │   └─── PATCH: Backwards-compatible bug fixes and security patches
     │   └─────── MINOR: Backwards-compatible new features, inputs, or outputs
     └─────────── MAJOR: Incompatible API changes, breaking inputs, or runtime shifts

Version Increment Rules for Actions

---

2. The Major Tag Floating Pattern

The standard distribution pattern endorsed by GitHub is the Major Tag Floating Pattern. Under this pattern, the action maintainer publishes exact immutable semantic release tags (e.g., v1.0.0, v1.0.1, v1.1.0) while simultaneously maintaining a mutable major tag (e.g., v1) that always points to the latest commit SHA within that major version.

Commit Graph & Tag Movement:

 [Commit A] ─── (tag: v1.0.0, tag: v1)
      │
 [Commit B] ─── (tag: v1.0.1, tag: v1)  <-- v1 moved forward to Commit B
      │
 [Commit C] ─── (tag: v1.1.0, tag: v1)  <-- v1 moved forward to Commit C
      │
 [Commit D] ─── (tag: v2.0.0, tag: v2)  <-- Breaking change: new v2 tag created
      │
 [Commit E] ─── (tag: v1.1.1, tag: v1)  <-- Patch backported to v1: v1 moved to Commit E

How Consumers Reference the Action

Consumers can choose their desired balance between stability and automated updates:

• uses: actions/checkout@v4: Recommended standard. Automatically receives all non-breaking features (v4.1.0), bug fixes, and security patches (v4.1.2) without requiring manual workflow edits.
• uses: actions/checkout@v4.1.1: Strict SemVer pinning. Pins to a specific minor/patch release. Will not automatically receive subsequent patch fixes.
• uses: actions/checkout@main: Anti-pattern for production. Tracks the development branch tip. Unstable, untested commits or breaking development changes can instantly break consuming CI/CD pipelines.

Moving Tags via Git CLI

To move a major floating tag manually after creating a patch release:

# 1. Create and push the specific patch tag
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3

# 2. Force-update the major floating tag locally and remotely
git tag -fa v1 -m "Update floating major tag v1 to v1.2.3"
git push origin v1 --force

---

3. Commit SHA Pinning: The Ultimate Security Posture

While floating major tags provide developer convenience, Git tags are mutable references. An attacker who compromises a developer's GitHub account, an organization's personal access token (PAT), or a third-party repository maintainer account could force-push an existing tag (e.g., v3) to point to malicious code designed to exfiltrate secrets or backdoor production builds.

To achieve maximum supply chain security, enterprise security frameworks (such as OpenSSF Scorecard and SLSA) mandate Full 40-character Commit SHA Pinning for all third-party actions.

# ✅ SECURE: Cryptographically immutable SHA pinning with human-readable comment
steps:
  - name: Check out repository
    uses: actions/checkout@b4ffde65f46336ab851b4c731e846067756f7004 # v4.1.1

  - name: Setup Node.js
    uses: actions/setup-node@60edb5dd545a775178f525247059d6427f4f91a9 # v4.0.2
    with:
      node-version: '20'

Comparison of Action Referencing Strategies

[!TIP] Automating SHA Updates: When pinning actions by full commit SHA, enable Dependabot version updates in .github/dependabot.yml with package-ecosystem: "github-actions". Dependabot automatically detects new action releases, opens PRs with updated commit SHAs, and maintains the inline # vX.Y.Z version comments.

---

4. Automating Tag Releases with Workflows

Action maintainers automate the compilation, packaging, and tag-moving process using GitHub Actions itself. Because JavaScript actions require bundled dependencies (dist/index.js) to be checked into Git, a release workflow ensures that builds are compiled and tags are synced atomically.

name: Release Action Version
on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+' # Trigger on SemVer tags like v1.2.3

permissions:
  contents: write

jobs:
  publish-release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies and compile bundle
        run: |
          npm ci
          npm run build # Bundles src/ into dist/index.js via @vercel/ncc

      - name: Extract Major Version
        id: version
        run: |
          TAG_NAME="${{ github.ref_name }}"
          MAJOR_TAG=$(echo "$TAG_NAME" | cut -d. -f1)
          echo "major_tag=$MAJOR_TAG" >> $GITHUB_OUTPUT

      - name: Update Floating Major Tag
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git tag -fa "${{ steps.version.outputs.major_tag }}" -m "Update ${{ steps.version.outputs.major_tag }} to ${{ github.ref_name }}"
          git push origin "${{ steps.version.outputs.major_tag }}" --force

---

5. Deprecating Actions and Runtime Versions

As actions evolve, authors must retire legacy versions, runtime targets, or entire repositories without breaking existing builds abruptly. GitHub Actions provides native deprecation mechanisms in action.yml.

name: 'Legacy Cloud Deployer'
description: 'Deploys artifacts to legacy storage endpoints'
# ⚠️ Deprecation message displayed as warning in runner logs
deprecationMessage: 'This action version is deprecated. Please migrate to my-org/cloud-deploy@v2 before December 2026.'

inputs:
  api-key:
    description: 'API authorization key'
    required: true

runs:
  using: 'node20'
  main: 'dist/index.js'

Deprecation Display & Runtime Migrations

• Runner Warning: When a workflow step executes an action containing deprecationMessage:, the runner displays the message as a prominent warning annotation in the workflow summary and execution log.
• Runtime Deprecation: When GitHub phases out older Node runtimes (e.g., node12, node16), actions specifying deprecated runtimes trigger automatic runner warnings. Maintainers must update runs.using to supported runtimes (such as node20) and release a new major version.