release-tagger

Simple semantic release tagger — reads a VERSION file, creates annotated git tags with build metadata, and optionally pushes them.

Install

npm install -g release-tagger
# or
npx release-tagger

Quick Start

# 1. Create a VERSION file in your repo root
echo "1.0.0" > VERSION

# 2. See what would happen (no changes made)
release-tagger --dry-run

# 3. Create the tag
release-tagger

# 4. Push to remote (optional)
release-tagger --push

The VERSION File

release-tagger reads a plain-text file (default: VERSION) in your repository root.

• Format: <major>.<minor>.<patch> — no quotes, no JSON, just the version string
• Pre-release suffixes are allowed but stripped when determining the base version

# VERSION file contents
1.2.0          → base version is 1.2.0
2.0.0-beta.1   → base version is 2.0.0 (suffix stripped)
  3.1.4  \n    → whitespace trimmed, base version is 3.1.4

If the file is missing or malformed, the tool exits with an error.

Tag Format

The final git tag follows this pattern: v<baseVersion>[-<preId>][+<build>]

| Scenario | Example | Result | |---|---|---| | First release, no pre-id | VERSION=1.0.0 | v1.0.0 (build 0 → no +N) | | First release, with pre-id | VERSION=1.0.0, --pre-id rc | v1.0.0-rc | | Second release, no pre-id | VERSION=1.0.0, auto-increment | v1.0.0+1 | | Second release, with pre-id | VERSION=1.0.0, --pre-id rc --build 1 | v1.0.0-rc+1 |

Key rule: build 0 produces a clean tag (v1.2.3 or v1.2.3-rc). Build > 0 appends +N.

Semver Compliance

release-tagger follows the Semantic Versioning 2.0.0 specification.

• The VERSION file contains MAJOR.MINOR.PATCH — the source of truth for your release version.
• The +N suffix is build metadata per semver spec. It does not affect version precedence: 1.0.0+1 and 1.0.0+999 are both equal to 1.0.0 in semver ordering.
• Build metadata is for tracking CI rebuilds or re-releases of the same source version. It does not bump the version.
• To produce a new semver version (e.g. 1.0.1), update the VERSION file. The tool does not auto-bump MAJOR.MINOR.PATCH.

VERSION = "1.0.0"
  → v1.0.0     (build 0)
  → v1.0.0+1   (build 1, same version)
  → v1.0.0+2   (build 2, same version)

echo "1.0.1" > VERSION
  → v1.0.1     (new version, build 0)

CLI Flags

| Flag | Description | Default | |---|---|---| | -f, --version-file <path> | Path to VERSION file | VERSION | | -p, --pre-id <id> | Pre-release identifier (e.g. rc, beta) | none | | -b, --build <number> | Build number (auto-increments if omitted) | auto | | --dry-run | Print what would happen without making changes | false | | --push | Push tag to remote (origin) after creation | false | | --repo-path <path> | Repository root path | cwd |

Examples

Standard release

# VERSION file contains: 1.0.0
release-tagger
# Output:
#   Base version : 1.0.0
#   Pre-release  : none
#   Build number : 0
#   Final tag    : v1.0.0
# ✅ Successfully tagged: v1.0.0

Pre-release build

release-tagger --pre-id rc --build 1
# → creates tag: v1.0.0-rc+1

Auto-increment build

# First run
release-tagger
# → v1.0.0+0

# Second run (no --build specified)
release-tagger
# → v1.0.0+1

Dry run (safe in CI)

release-tagger --dry-run
# → prints what it would do, makes no changes

Push to remote

release-tagger --push
# creates tag locally, then: git push origin <tag>

Different repo path

release-tagger --repo-path /path/to/other/repo

Error Behavior

| Scenario | What Happens | |---|---| | Missing VERSION file | Exits with error: VERSION file not found: <path> | | Invalid semver (e.g. abc.1.0) | Exits with error: Invalid semver in VERSION file: <value> | | Tag already exists | Skips creation, exits cleanly: Tag v1.0.0+0 already exists. Skipping. | | Push fails | Logs error, exits 1. Local tag is preserved. |

CI / GitHub Actions

name: Release Tag

on:
  push:
    branches: [main]

jobs:
  tag:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run build
      - name: Create release tag
        run: release-tagger --push
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

For more CI examples, see docs/USAGE.md.

How Build Auto-Increment Works

The tool scans existing git tags that match the current prefix and picks the highest build number, then adds 1.

Tags matching "v1.0.0+*":  v1.0.0+0  v1.0.0+1  v1.0.0+5
Highest = 5
Next build = 6

Pre-release tags like v1.0.0-rc are tracked separately from v1.0.0+* tags.

Contributing

See CONTRIBUTING.md and docs/CONTRIBUTING-GUIDE.md.

License

Personal Noncommercial Redistribution License — see LICENSE and LEGAL.md.