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 transient tags (v0.0.0-rc.1 or v0.0.0-pr-123.1), main branch creates production versions (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.

💬

Commit Commands

Include /major or /minor in commit messages to control version bumps. No configuration needed, just commit and go.

📅

Yearly Versioning

Use year as major version (2025.0.0 format). Automatically updates to new year when incrementing minor version.

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 transient preview tag: v0.0.0-pr-42.1

Merge PR to dev branch

Increments patch: v1.3.5-dev

Create PR from dev branch to main branch

Creates transient RC tag: v0.0.0-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: v0.0.0-rc.1

                      # PR to dev: v0.0.0-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

yearly

Use year as major version (e.g., 2025.0.0) and auto-update on new year

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

no-tags

Skip tag creation and pushing (only calculate version)

Default: false

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}

update-version-files

Automatically update version in common version files (package.json, pyproject.toml, etc.) without committing

Default: true

version-file-paths

Additional paths to search for version files (space or newline separated). Useful for monorepos

Default: (empty)

patch-reset-value

Value to reset PATCH to when incrementing MAJOR or MINOR

Default: 0

📤 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

environment

Environment type

Example: production, dev, staging, or pr-42

suffix

Version suffix (empty for production)

Example: dev, rc, pr-42, or empty

future-version

Actual semantic version for transient environments (RC/PR) before 0.0.0

Example: 1.2.3 (when version is 0.0.0-rc.1)

stable-version

Latest stable production version (without pre-release suffix)

Example: 1.2.3