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: tagimage: python:3.13-slimvariables:
SEMVERTAG_STRATEGY: branch-prefix # or: conventional-commitsbefore_script:
- pip install --quiet 'uv>=0.4,<1'script:
- uvx 'semvertag>=0.5.0,<1' tagrules:
- 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.

Use it in GitHub Actions

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

name: semvertagon:
push:
branches: [main]permissions:
contents: writejobs:
tag:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4with:
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.

Strategies

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

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.