git-semver-tagger

Tagger CLI

An opinionated program for automatic semantic versioning via git tags and information in commits.

Installation

You can install the tool using any NPM-like system.

Local Example

npm i -D git-semver-tagger # this will install it into a project as a dev dependency

npx tagger calculate-version # You can use npx to run a project's programs easily

Global Example

npm i -g git-semver-tagger # this will install it globally into npm

tagger calculate-version # Now it should be available via NPM's path on your shell.

Commands

Calculate Version

The calculate-version command will generate a new version number based on all of the commits since the last tag, and output as a string.

Basic usage:

tagger calculate-version

Output: 1.2.3-SNAPSHOT

Tag

The tag command will create a tag with the given version and push it back to the repository.

We recommend this command only is run after the build is validated. Use discernment to decide if it should happen before publication of artifacts, or afterward.

Basic usage:

tagger tag --version 1.2.3 --release-branch main

Structured Output

Both commands support machine-readable JSON output for CI/CD pipelines and automation scripts via the --format flag.

Format Options

• --format=text (default): Human-readable text output
• --format=json: Structured JSON output

Calculate Version JSON Output

Example command:

tagger calculate-version --format=json

Success response:

{
  "status": "success",
  "data": {
    "version": "1.2.3-SNAPSHOT",
    "snapshot": true,
    "snapshotReasons": [
      "DIRTY",
      "AHEAD"
    ]
  }
}

Error response:

{
  "status": "error",
  "error": "HEAD is detached (not pointing at any branch)",
  "code": "CONFIGURATION_ERROR"
}

Fields:

• status: "success" or "error"
• data.version: Calculated semantic version string
• data.snapshot: Boolean indicating if this is a snapshot version
• data.snapshotReasons: Array of reasons why this is a snapshot (e.g., "DIRTY", "AHEAD")
• error: Human-readable error message (only in error responses)
• code: Machine-readable error code (only in error responses)

Tag JSON Output

Example command:

tagger tag --version 1.2.3 --release-branch main --format=json

Success response:

{
  "status": "success",
  "data": {
    "tag": "1.2.3"
  }
}

Error response:

{
  "status": "error",
  "error": "Failed to create tag",
  "code": "TAG_ERROR"
}

Fields:

• status: "success" or "error"
• data.tag: The tag name that was created
• error: Human-readable error message (only in error responses)
• code: Machine-readable error code (only in error responses)

Error Codes

• CONFIGURATION_ERROR: Invalid configuration or repository state (e.g., detached HEAD)
• TAG_ERROR: Failed to create or push tag

CI Integration Examples

Extract version in GitHub Actions:

- name: Calculate version
  id: version
  run: |
    VERSION=$(tagger calculate-version --format=json | jq -r '.data.version')
    echo "version=$VERSION" >> $GITHUB_OUTPUT

- name: Use version
  run: echo "Building version ${{ steps.version.outputs.version }}"

Extract version in bash:

# Get version
VERSION=$(tagger calculate-version --format=json 2>/dev/null | jq -r '.data.version')

# Check if snapshot
IS_SNAPSHOT=$(tagger calculate-version --format=json 2>/dev/null | jq -r '.data.snapshot')

if [ "$IS_SNAPSHOT" = "true" ]; then
  echo "This is a snapshot build"
fi

Error handling:

OUTPUT=$(tagger calculate-version --format=json 2>&1)
STATUS=$(echo "$OUTPUT" | jq -r '.status')

if [ "$STATUS" = "error" ]; then
  ERROR_MSG=$(echo "$OUTPUT" | jq -r '.error')
  ERROR_CODE=$(echo "$OUTPUT" | jq -r '.code')
  echo "Error ($ERROR_CODE): $ERROR_MSG"
  exit 1
fi

Common Errors and Troubleshooting

Lightweight Tags

Error: found N tag(s) (...) but it is/they are lightweight.

Cause: Tagger requires annotated tags (created with git tag -a) because they store metadata like tagger name, email, and timestamp. Lightweight tags (created with git tag <name>) don't include this information.

Solution: Recreate the tag(s) as annotated tags. The error message will provide exact commands, for example:

git tag -d 1.0.0
git tag -a 1.0.0 <sha> -m "1.0.0"
git push --force origin 1.0.0

Replace <sha> with the commit hash where the tag should point (often the same commit the lightweight tag pointed to).

Permission Errors When Pushing Tags

Error: Command failed: git push --tags (exit code 128) or exit code 403

Common causes:

• The account running tagger doesn't have push permission on the repository
• CI/CD pipelines often use restricted service accounts by default

Solutions:

For Azure DevOps:

• Go to Project Settings → Repositories → Security
• Find the Build Service identity (e.g., <Project Name> Build Service)
• Grant both Contribute and Create tag permissions
• Ensure "Allow scripts to access the OAuth token" is enabled in your pipeline YAML:

  - checkout: self
    persistCredentials: true
  

For GitHub Actions:

• Add write permissions to your workflow job:

  jobs:
    build:
      permissions:
        contents: write  # Required for pushing tags
  

• Ensure you're not using a read-only GITHUB_TOKEN

For GitLab CI:

variables:
  GIT_STRATEGY: clone
  
before_script:
  - git config --global user.email "[e-mail]"
  - git config --global user.name "CI Bot"

No Tags Exist

Error: repository has no tags.

Cause: This is a new repository or no tags have been created yet.

Solution: Create an initial tag manually to establish the version baseline:

git tag -a 0.1.0 -m "Initial version"
git push origin 0.1.0

After this, tagger can calculate subsequent versions automatically.

Help

For a full listing of the available options in the program, please use the built-in help command.

tagger --help