Auto Version - Automatic Semantic Versioning for GitHub Actions

What Does It Do?

Automatically creates version tags based on your workflow context

🎯

Auto-Detection

Detects if you're pushing to main branch, dev branch, or creating a PR and generates the right version tag automatically

🔢

Smart Versioning

Dev branch increments patch (v1.2.3-dev), PRs get unique tags (v1.2.3-rc.1 or v1.2.3-pr-123.1), main branch strips suffixes (v1.2.3)

🏷️

Git Tag Based

Uses existing git tags to calculate versions. No version files, no configuration files, just git tags

📝

File Editing

Automatically update files with new versions (perfect for GitHub Actions that reference Docker images). Optional push control for advanced workflows.

Version Journey

See how versions evolve through your development workflow

Push commit to dev branch

Increments patch: v1.3.4-dev

Create PR to dev branch

Creates preview tag: v1.3.4-pr-42.1

Merge PR to dev branch

Increments patch: v1.3.5-dev

Create PR from dev branch to main branch

Creates RC tag: v1.3.5-rc.1

Merge PR to main branch (production release)

Strips suffix: v1.3.5

Next commit to dev branch (after production release)

Bumps minor, resets patch: v1.4.0-dev

Direct commit to main branch (hotfix scenario)

Increments patch from last production tag: v1.3.6

Usage

Add to your workflows - one action, all environments

🌿 Dev Branch Workflow

              name: Dev Deploy

              on:

                push:

                  branches:
              [dev]

              jobs:

                deploy:

                  runs-on:
              ubuntu-latest

                  permissions:

                    contents:
              write

                  steps:

                    - uses:
              actions/checkout@v4

                      with:

                        fetch-tags:
              true

                    - name:
              Auto Version and Tag

                      uses:
              starburst997/auto-version@v1

                      id:
              version

                    - name:
              Deploy to Dev

                      run:
              echo "Deploying ${{ steps.version.outputs.version }}"

🔀 Pull Request Workflow

              name: PR Deploy

              on:

                pull_request:

                  branches:
              [main, dev]

              jobs:

                deploy:

                  runs-on:
              ubuntu-latest

                  permissions:

                    contents:
              write

                  steps:

                    - uses:
              actions/checkout@v4

                      with:

                        fetch-tags:
              true

                    - name:
              Auto Version and Tag

                      uses:
              starburst997/auto-version@v1

                      id:
              version

                      # PR to main: v1.2.3-rc.1

                      # PR to dev: v1.2.3-pr-42.1

                    - name:
              Deploy Preview

                      run:
              echo "Deploying ${{ steps.version.outputs.version }}"

🚀 Production Workflow

              name: Production Deploy

              on:

                push:

                  branches:
              [main]

              jobs:

                deploy:

                  runs-on:
              ubuntu-latest

                  permissions:

                    contents:
              write

                  steps:

                    - uses:
              actions/checkout@v4

                      with:

                        fetch-tags:
              true

                    - name:
              Auto Version and Tag

                      uses:
              starburst997/auto-version@v1

                      id:
              version

                      with:

                        update-major-minor:
              true
              # Update v1, v1.2 tags

                    - name:
              Create Release

                      env:

                        GH_TOKEN:
              ${{ github.token }}

                      run:
              |

                        gh
              release create ${{ steps.version.outputs.tag }} \

                          --title
              "Release ${{ steps.version.outputs.version }}"
              \

                          --generate-notes

🏷️ GitHub Action with File Update

              name: Release Action

              on:

                push:

                  branches:
              [main]

              jobs:

                release:

                  runs-on:
              ubuntu-latest

                  permissions:

                    contents:
              write

                  steps:

                    - uses:
              actions/checkout@v4

                      with:

                        fetch-depth:
              0

                    - name:
              Auto Version with File Update

                      uses:
              starburst997/auto-version@v1

                      with:

                        update-major-minor:
              true

                        edit-file:
              "action.yml"

                        edit-commit-message:
              "chore: update docker to {version}"

                        # Automatically updates action.yml with new version

                    - name:
              Build and Push Docker

                      run:
              echo "Docker image will use correct version"

Reference

Complete inputs and outputs documentation

📥 Inputs

main-branch

Name of the main/production branch

Default: main

dev-branch

Name of the development branch

Default: dev

default-version

Starting version if no tags exist

Default: 1.0.0

update-major-minor

Update floating tags (v1, v1.2) to point to latest version

Default: false

git-user-name

Git user name for tagging

Default: github-actions[bot]

git-user-email

Git user email for tagging and commits

Default: github-actions[bot]@users.noreply.github.com

git-push

Push changes and tags to remote repository

Default: true

edit-file

File to update with new version (e.g., action.yml). If empty, skipped

Default: (empty)

edit-search-pattern

Search pattern for version replacement

Default: ${{ github.repository }}:

edit-commit-message

Commit message template for file edit (use {version} placeholder)

Default: chore: update version to {version}

📤 Outputs

version

Calculated version without 'v' prefix

Example: 1.2.3 or 1.2.3-dev

tag

Git tag with 'v' prefix

Example: v1.2.3 or v1.2.3-dev