semvertag

PyPI version Supported Python versions Downloads Coverage CI License GitHub stars Context7 uv Ruff ty

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

uvx semvertag tag

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 latest 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.

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: actions/checkout@v4
 with:
 fetch-depth: 0
 - 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. fetch-depth: 0 matters — the default 1 misses tag-relative history. See GitHub Actions docs for token scopes, GitHub Enterprise setup, outputs, and troubleshooting.

• branch-prefix (default): the latest 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 latest 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.

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).

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