GitLab CI中如何用setuptools_scm将Git标签转为Python版本？

1. 先搞定CI环境的Git依赖 #

setuptools_scm要读取Git标签和提交记录才能生成版本号，所以得确保GitLab CI能获取完整的仓库数据：

• 要么在项目CI/CD设置里把「Git克隆深度」改成0（完整克隆）；
• 要么在任务的before_script里加一句git fetch --tags，手动拉取所有标签。

2. 用setuptools_scm获取版本号 #

有两种简单方式拿到对应Git标签的版本号，存到PACKAGE_VERSION环境变量里即可：

方式一：直接调用命令行工具 #

setuptools_scm自带命令行工具，一行命令就能输出版本号：

PACKAGE_VERSION=$(python3 -m setuptools_scm)

方式二：写个小Python脚本（灵活度更高） #

如果需要自定义版本规则（比如保留标签的v前缀），可以写个极简脚本：

# get_version.py
from setuptools_scm import get_version
print(get_version(root=".", relative_to=__file__))

然后在CI中执行脚本获取版本号：

PACKAGE_VERSION=$(python3 get_version.py)

3. 修改GitLab CI配置文件 #

把版本号获取逻辑整合到现有流水线中，修改后的配置示例如下：

[…]

stages:
  - […]
  - deploy
  - deploytest

pip-upload:
  stage: deploy
  rules:
    - if: '$CI_COMMIT_TAG && $CI_COMMIT_TAG =~ /v[1-9].+/'
  before_script:
    - git fetch --tags  # 确保能获取所有标签
    - pip install setuptools_scm  # 安装依赖工具
  script:
    - python3 setup.py sdist
    - python3 -m twine upload --repository-url […] dist/*

test-pip:
  stage: deploytest
  rules:
    - if: '$CI_COMMIT_TAG && $CI_COMMIT_TAG =~ /v[1-9].+/'
  before_script:
    - git fetch --tags
    - pip install setuptools_scm
    - export PACKAGE_VERSION=$(python3 -m setuptools_scm)  # 把版本号存入环境变量
  script:
    - python3 -m pip install --extra-index-url […] --upgrade --pre "mypackage==$PACKAGE_VERSION"
    - cd /tmp
    - python3 -m pytest --pyargs mypackage

关键细节说明 #

• setuptools_scm默认会自动剥离Git标签的v前缀（比如标签v1.2.3会生成版本号1.2.3），刚好符合PyPI的版本规范，无需额外处理。
• 如果需要保留v前缀或自定义版本格式，可以在setup.py中添加配置：

  # setup.py
  from setuptools import setup
  setup(
      use_scm_version={"normalize": False}
  )
  

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