modern-python/semvertag: Auto-tag GitHub & GitLab repos with semantic version tags from CI · GitHub

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.