GitLab部署PyPI包时自动更新版本的问题求助

一、当前配置的核心问题 #

1. setuptools-git-versioning 配置不完整 #

你仅开启了工具的enabled开关，但未指定版本生成格式、标签匹配规则等核心逻辑，工具无法确定如何从Git历史生成合法版本号。

2. GitLab CI 浅克隆限制 #

GitLab CI 默认采用浅克隆（--depth=1）拉取代码，导致工具无法获取完整的Git标签、提交历史，进而无法生成动态版本。

3. 依赖安装逻辑冗余 #

CI脚本中单独安装setuptools-git-versioning的操作多余，build-system段已声明该依赖，python -m build会自动处理相关依赖安装。

二、修复后的配置与脚本 #

1. 更新 pyproject.toml #

补充版本生成规则，明确标签匹配格式、无标签时的 fallback 版本等：

[build-system]
requires = ["setuptools>=61.0", "wheel", "setuptools-git-versioning==1.13.5"]
build-backend = "setuptools.build_meta"

[tool.setuptools-git-versioning]
enabled = true
# 版本格式：标签.提交数.哈希后缀
format = "{tag}.{post}.{hash}"
# 匹配v开头的语义化标签（如v1.0.0）
tag-match = "v[0-9]*"
# 无标签时的基础版本
fallback-version = "0.0.0"
# 本地有未提交修改时追加标记
dirty-tag = ".dirty"

[project]
name = "my-package"
dynamic = ["version"]

2. 调整 GitLab CI 部署脚本 #

解决浅克隆问题，优化依赖安装流程：

deploy:
  stage: deploy-package
  image: python:3.11-slim
  script:
    # 拉取完整Git历史与标签，解决浅克隆限制
    - git fetch --tags --prune --unshallow
    # 升级pip并安装构建、上传工具
    - pip install --upgrade pip build twine
    # 执行包构建（自动处理build-system声明的依赖）
    - python -m build
    # 上传到GitLab私有PyPI仓库
    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*
  only:
    - tags
    - main # 按需指定需要触发部署的分支

三、更优替代方案：setuptools-scm #

如果setuptools-git-versioning仍有兼容性问题，推荐使用Python社区更主流的setuptools-scm，它对Git环境的适配更完善：

1. 更新 pyproject.toml #

[build-system]
requires = ["setuptools>=61.0", "wheel", "setuptools-scm>=8.0"]
build-backend = "setuptools.build_meta"

[tool.setuptools-scm]
# 指定标签前缀（如v1.0.0中的v）
tag_prefix = "v"
# 可选：生成版本文件供包内部代码调用版本号
write_to = "src/my_package/_version.py"

[project]
name = "my-package"
dynamic = ["version"]

2. CI 脚本调整 #

仅需保留解决浅克隆的步骤，其余逻辑与之前一致：

deploy:
  stage: deploy-package
  image: python:3.11-slim
  script:
    - git fetch --tags --prune --unshallow
    - pip install --upgrade pip build twine
    - python -m build
    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*
  only:
    - tags
    - main

关键注意事项 #

• 确保Git仓库存在符合规则的标签（如v1.0.0），工具会基于最近的标签生成版本号
• 非标签分支部署时，工具会生成类似1.0.0.dev12+gabc123的开发版本号
• 确认GitLab CI的CI_JOB_TOKEN拥有拉取代码、上传包的权限

内容的提问来源于stack exchange，提问作者Abhiram Devisetti