VMN Action

Automated semantic versioning for GitHub Actions, powered by vmn.

Language-agnostic, git-tag-based versioning with support for monorepos, multi-app, release candidates, and conventional commits.

Quick Start

name: Version Stamp

on:
  push:
    branches: [main]

jobs:
  stamp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - id: vmn
        uses: progovoy/vmn-action@latest
        with:
          app-name: my_app
          do-stamp: true
          stamp-mode: patch
        env:
          GITHUB_TOKEN: ${{ github.token }}

      - run: echo "Stamped version ${{ steps.vmn.outputs.verstr }}"

Inputs

Input	Type	Required	Default	Description
app-name	string	Yes	—	Name of the app to stamp
do-stamp	boolean	No	false	Perform a version stamp
stamp-mode	choice	No	none	Release mode: major, minor, patch, or none
release-candidate	boolean	No	false	Enter release candidate mode
prerelease-name	string	No	rc	Prerelease suffix (e.g., rc produces 1.2.3-rc.1)
release	boolean	No	false	Release a prerelease version to final
stamp-from-version	string	No	—	Override the base version for stamping
skip-version	boolean	No	false	Skip versions between release candidates
do-gen	boolean	No	false	Generate a version file from a Jinja2 template
gen-template-path	string	No	—	Path to Jinja2 template file
gen-output-path	string	No	—	Path for generated output file
gen-custom-yaml-path	string	No	—	Path to custom YAML params file
show-log-on-error	boolean	No	false	Show vmn log on error
debug-mode	boolean	No	false	Enable extra debug logging
install-nonstable-vmn-version	boolean	No	false	Install latest RC version of vmn

Outputs

Output	Description
verstr	The version string after stamping (e.g., 1.2.3)
dirty	true if changes exist since last stamp
is_in_rc_mode	true if the app is in release candidate mode
verbose_yaml	Full vmn show --verbose output as YAML

Examples

Basic Stamp

Stamp a patch version on every push to main:

name: Stamp Version

on:
  push:
    branches: [main]

jobs:
  stamp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - id: vmn
        uses: progovoy/vmn-action@latest
        with:
          app-name: my_app
          do-stamp: true
          stamp-mode: patch
        env:
          GITHUB_TOKEN: ${{ github.token }}

      - run: echo "Version: ${{ steps.vmn.outputs.verstr }}"

Manual Stamp with Mode Selection

Use workflow_dispatch to choose the release mode at trigger time:

name: Manual Stamp

on:
  workflow_dispatch:
    inputs:
      stamp_mode:
        type: choice
        description: Release mode
        options:
          - patch
          - minor
          - major
        required: true

jobs:
  stamp:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - id: vmn
        uses: progovoy/vmn-action@latest
        with:
          app-name: my_app
          do-stamp: true
          stamp-mode: ${{ inputs.stamp_mode }}
        env:
          GITHUB_TOKEN: ${{ github.token }}

      - run: echo "Version: ${{ steps.vmn.outputs.verstr }}"

Release Candidate Workflow

RC workflows have three phases:

1. First RC — Start a release candidate from a released version:

- uses: progovoy/vmn-action@latest
  with:
    app-name: my_app
    do-stamp: true
    stamp-mode: minor          # The bump for the eventual release
    release-candidate: true
  env:
    GITHUB_TOKEN: ${{ github.token }}
# Result: 1.2.0-rc.1

2. Subsequent RCs — Increment the RC number (no stamp-mode needed):

- uses: progovoy/vmn-action@latest
  with:
    app-name: my_app
    do-stamp: true
    release-candidate: true
  env:
    GITHUB_TOKEN: ${{ github.token }}
# Result: 1.2.0-rc.2, 1.2.0-rc.3, ...

3. Release — Promote the RC to a final release:

- uses: progovoy/vmn-action@latest
  with:
    app-name: my_app
    do-stamp: true
    release: true
  env:
    GITHUB_TOKEN: ${{ github.token }}
# Result: 1.2.0

Monorepo / Multi-App

Stamp multiple apps independently in one workflow:

jobs:
  stamp:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        app: [frontend, backend, api-gateway]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - id: vmn
        uses: progovoy/vmn-action@latest
        with:
          app-name: ${{ matrix.app }}
          do-stamp: true
          stamp-mode: patch
        env:
          GITHUB_TOKEN: ${{ github.token }}

      - run: echo "${{ matrix.app }} version: ${{ steps.vmn.outputs.verstr }}"

Version File Generation

Generate a version file from a Jinja2 template:

- uses: progovoy/vmn-action@latest
  with:
    app-name: my_app
    do-gen: true
    gen-template-path: version.jinja2
    gen-output-path: version.txt
  env:
    GITHUB_TOKEN: ${{ github.token }}

- run: cat version.txt

Permissions

The action requires a GITHUB_TOKEN environment variable for:

• Permission checks (verifies the triggering user has write access)
• Git operations (push tags)

The default ${{ github.token }} works for most cases. For cross-repo scenarios, use a Personal Access Token with repo scope.

Important Notes

• fetch-depth: 0 is recommended for conventional commits / changelog analysis. For basic stamping, vmn works with shallow clones — it fetches tags automatically.
• The action automatically runs vmn init and vmn init-app if they haven't been run yet.
• Version information is stored in git tags, not in files — your repo stays clean.

Links

• vmn CLI documentation — full feature reference
• vmn on PyPI — install locally with pip install vmn
• Report an issue