GitLab CI/CD中Python项目自动版本发布的最优实现方案问询

你的release分支方案合理性 #

创建release/v<x.xx.xx>分支再合并主分支的方案是合理的：

• 能隔离发布准备工作（如版本号更新、最终测试）和日常开发，避免主分支频繁变更发布相关内容
• 便于回溯每个版本的发布记录，出现问题时快速定位

但需要解决两个核心问题：识别release分支合并触发流水线、提取版本号，以下是具体实现方式和更优流程。

更优实现流程（GitFlow风格） #

推荐采用「release分支准备 → 合并主分支 → 自动打标签 → 触发编译/发布」的自动化流程，替代手动打标签，解决你之前标签无法同步主分支的问题：

1. 调整CI规则，自动识别release分支合并并打标签 #

添加一个前置job，当release/v*分支合并到主分支时，自动提取版本号并在主分支提交上打标签：

create_tag_job:
  stage: .pre
  rules:
    - if: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^release\/v\d+\.\d+\.\d+$/
  script:
    # 从release分支名提取版本号（如release/v1.0.0 → v1.0.0）
    - VERSION=$(echo "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" | sed 's/release\///')
    # 校验分支版本与pyproject.toml版本一致（可选，避免版本 mismatch）
    - CURRENT_PROJECT_VERSION=$(poetry version --short)
    - if [ "$VERSION" != "v$CURRENT_PROJECT_VERSION" ]; then echo "版本不匹配：分支版本$VERSION，项目版本v$CURRENT_PROJECT_VERSION"; exit 1; fi
    # 配置Git身份并打标签
    - git config --global user.name "GitLab CI/CD"
    - git config --global user.email "ci@your-project.com"
    - git tag -a "$VERSION" -m "Release $VERSION"
    - git push origin "$VERSION"

注意：需在项目CI/CD设置中，给流水线角色开启推送标签的权限。

2. 修改编译与发布job的触发规则 #

原规则依赖CI_MERGE_REQUEST_TARGET_BRANCH_NAME，但打标签时该变量不存在，需调整为仅判断标签存在：

nuitka_job_windows:
  stage: nuitka_windows
  tags: [windows]
  needs: [wheel_build_job]
  rules: 
    - if: $CI_COMMIT_TAG != null
  script:
    # 安装nuitka依赖（若未在poetry dev依赖中）
    - poetry add nuitka --dev
    # 执行nuitka编译（示例：打包主入口文件为单可执行文件）
    - poetry run python -m nuitka --standalone --onefile --output-filename my_project.exe my_python_project/main.py
    # 将产物移动到dist目录以便上传artifacts
    - mv my_project.exe dist/
  artifacts:
    paths:
      - dist/my_project.exe

nuitka_job_linux:
  stage: nuitka_linux
  tags: [linux]
  needs: [wheel_build_job]
  rules: 
    - if: $CI_COMMIT_TAG != null
  script:
    - poetry add nuitka --dev
    - poetry run python -m nuitka --standalone --onefile --output-filename my_project.bin my_python_project/main.py
    - mv my_project.bin dist/
  artifacts:
    paths:
      - dist/my_project.bin

release_job:
  stage: release
  needs: 
    - job: wheel_build_job
      optional: false
    - job: doc_build_job
      optional: false
    - job: nuitka_job_linux
      optional: true
    - job: nuitka_job_windows
      optional: true
  rules:
    - if: $CI_COMMIT_TAG != null
  script:
    - echo "执行发布：$CI_COMMIT_TAG"
    - curl --location --output /usr/local/bin/release-cli "https://gitlab.com/api/v4/projects/gitlab-org%2Frelease-cli/packages/generic/release-cli/latest/release-cli-linux-amd64"
    - chmod +x /usr/local/bin/release-cli
    # 用release-cli创建GitLab Release，关联所有产物
    - release-cli create --name "Release $CI_COMMIT_TAG" --tag-name "$CI_COMMIT_TAG" --description "$CI_COMMIT_DESCRIPTION" \
        --assets-link "{\"name\":\"Linux 可执行文件\",\"url\":\"$CI_PROJECT_URL/-/jobs/$CI_JOB_ID/artifacts/raw/dist/my_project.bin\"}" \
        --assets-link "{\"name\":\"Windows 可执行文件\",\"url\":\"$CI_PROJECT_URL/-/jobs/$WINDOWS_JOB_ID/artifacts/raw/dist/my_project.exe\"}" \
        --assets-link "{\"name\":\"Python Wheel 包\",\"url\":\"$CI_PROJECT_URL/-/jobs/$CI_JOB_ID/artifacts/raw/dist/*.whl\"}"
  release:
    tag_name: "$CI_COMMIT_TAG"
    description: "$CI_COMMIT_DESCRIPTION"

3. 版本号提取方式 #

有两种可靠的版本号提取方式，按需选择：

• 从release分支名提取：通过sed命令从release/v1.0.0中提取v1.0.0，适合分支名与版本严格绑定的场景
• 从pyproject.toml读取：用poetry version --short直接获取项目定义的版本号，确保分支与项目版本一致，避免人为错误

关键注意事项 #

• 确保nuitka编译环境满足依赖：Windows/Linux runner需安装对应系统的编译工具链（如Windows的Visual Studio Build Tools、Linux的gcc）
• 所有编译产物需通过artifacts上传，才能在release job中引用
• 若不需要release分支，也可直接在主分支更新版本号后手动打标签，但release分支的方式更适合多版本并行开发的场景

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