Auto-tag your GitLab or GitHub repository with semantic version tags from CI. One tool covers both providers and offers two bump strategies.

Install

uvx semvertag tag

semvertag bumps from the highest existing semver tag and never creates the first one. Before the first run, create a semver tag such as 0.1.0, or v0.1.0 if you want v-prefixed tags: each new tag keeps the prefix of the one it bumps from.

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.10.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 and the tag history, decides the semver bump, and creates the new tag through 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

The default branch-prefix strategy requires the head commit on the default branch to be a merge commit whose subject names a feature/ (minor), bugfix/, or hotfix/ (patch) branch.

The conventional-commits strategy parses the head commit's Conventional Commits header (feat: minor, fix:/perf: patch, ! or BREAKING CHANGE: major).

Both are configurable through environment variables. See docs for the full configuration surface.

Built with

semvertag stands on other modern-python libraries:

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

📚 Documentation

📦 PyPI

📝 License

Part of modern-python

Browse the full list of templates and libraries in modern-python. The org profile has the categorized index.