semvertag 0.8.5

Auto-tag your GitLab or GitHub repository with semantic version tags from CI — one tool, two strategies, two providers.

Install

uvx semvertag tag

Use it in GitLab CI

Paste this job into your .gitlab-ci.yml:

stages: [tag]

semvertag:
  stage: tag
  image: python:3.13-slim
  variables:
    SEMVERTAG_STRATEGY: branch-prefix  # or: conventional-commits
  before_script:
    - pip install --quiet 'uv>=0.4,<1'
  script:
    - uvx 'semvertag>=0.5.0,<1' tag
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

It runs uvx semvertag tag against your repo on the default branch. semvertag inspects the head commit + tag history, decides the appropriate semver bump, and creates the new tag via the GitLab API.

A one-line include: - component: … via the GitLab CI Catalog will replace this snippet once the component is published. For now, paste the job inline.

Use it in GitHub Actions

Paste this workflow into .github/workflows/semvertag.yml:

name: semvertag
on:
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
      - uses: modern-python/semvertag@v0

semvertag auto-detects GitHub Actions, picks the bump from the latest commit, and creates the tag ref via the GitHub API. It never reads the working tree, so the job needs no actions/checkout step at all. See GitHub Actions docs for token scopes, GitHub Enterprise setup, outputs, and troubleshooting.

Strategies

• branch-prefix (default): the head commit on the default branch must be a merge commit whose source branch starts with feature/ (minor), bugfix/, or hotfix/ (patch).
• conventional-commits: parses the head commit's Conventional Commits header (feat: minor, fix:/perf: patch, ! or BREAKING CHANGE: major).

Both are configurable via env vars. See docs for the full configuration surface.

Built with

semvertag stands on other modern-python libraries:

• modern-di-typer — dependency-injection wiring for the Typer CLI. semvertag resolves its settings, API providers, and bump strategies through a modern_di container (semvertag/ioc.py).
• httpware — the resilient HTTP client both providers use for the GitLab/GitHub REST calls (retries, timeouts, typed decoding, secret redaction).

📚 Documentation

📦 PyPI

📝 License

Part of modern-python

Browse the full list of templates and libraries in modern-python — see the org profile for the categorized index.