基于python-semantic-release与Woodpecker CI：如何支持RC构建并为正式版本保留分组变更日志？

我来帮你梳理这个问题的核心解决方案——你遇到的关键矛盾就是semantic-release的「提交消耗」机制（处理过的提交会被标记为已完成，后续不会再纳入版本计算）和你需要的分组式正式变更日志、RC版本测试制品之间的冲突。下面是一套适配你的技术栈的实践方案：

核心思路 #

让RC版本仅负责生成带规范版本号的测试制品（比如Docker镜像），绝不修改Git仓库的变更日志或推送版本标签；正式发布时，由main分支统一扫描所有未处理的提交，生成单一版本的分组式变更日志。这样既保留了RC版本的测试标识，又不会让提交被提前消耗。

1. 推荐分支结构设计 #

• main：正式发布唯一分支，仅接收从release/*分支的普通合并（禁止squash/rebase，必须保留完整提交历史）
• dev：日常开发分支，功能分支通过PR合并到此（可以用squash merge简化历史，不影响后续流程）
• release/x.y：预发布准备分支，当需要筹备新版本时，从dev拉出对应版本线的分支（比如release/2.1），专门用于生成RC版本和最终发布准备

2. Woodpecker CI 分阶段配置 #

（1）Dev分支：持续集成+快照部署 #

dev分支只做CI验证和快照部署，不需要运行semantic-release，用提交SHA短码作为镜像标识（比如my-app:dev-a1b2c3d），既满足测试需求，又不会提前消耗提交。

Woodpecker CI简化配置：

pipeline:
  test:
    image: python:3.11
    commands:
      - pip install -r requirements.txt
      - pytest --cov=./src
  build-dev-image:
    image: docker:24
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    commands:
      - docker build -t my-registry/my-app:dev-${CI_COMMIT_SHA:0:7} .
      - docker push my-registry/my-app:dev-${CI_COMMIT_SHA:0:7}
    when:
      branch: dev

（2）Release分支：生成RC版本+测试部署 #

在release/x.y分支运行semantic-release，但限制它只做版本计算和制品发布，禁止修改Git仓库内容。通过配置让semantic-release仅输出RC版本号，用这个版本号构建测试镜像，不提交变更日志或推送标签。

首先调整pyproject.toml中的semantic-release配置：

[tool.semantic_release]
version_toml = ["pyproject.toml:version"]
branch = "release/2.1"  # 对应当前release分支的版本线
prerelease_token = "rc"
# 关键：禁止自动提交变更日志和推送标签到Git
commit = false
tag = false
# 自定义钩子：用生成的RC版本号构建镜像
[tool.semantic_release.hooks]
post_version = "docker build -t my-registry/my-app:${NEW_VERSION} . && docker push my-registry/my-app:${NEW_VERSION}"

然后是Woodpecker CI在release分支的配置：

pipeline:
  test:
    image: python:3.11
    commands:
      - pip install -r requirements.txt
      - pytest --cov=./src
  generate-rc:
    image: python:3.11
    commands:
      - pip install python-semantic-release
      - semantic-release version --prerelease  # 计算并输出RC版本号
      - semantic-release publish  # 触发钩子发布RC镜像
    when:
      branch: release/*

每次在release/x.y分支推送提交，semantic-release都会基于当前提交历史计算出下一个RC版本（比如v2.1.0-rc.1、rc.2），但不会修改Git仓库的任何内容——所有提交依然处于「未消耗」状态。

（3）Main分支：正式发布+统一变更日志 #

当RC版本测试通过后，将release/x.y分支普通合并到main分支（保留所有提交历史）。此时在main分支运行完整的semantic-release，它会扫描从上一次正式发布以来的所有提交，统一生成一个正式版本（比如v2.1.0）和分组式的变更日志，同时推送版本标签到Git仓库。

pyproject.toml中main分支的semantic-release配置：

[tool.semantic_release]
version_toml = ["pyproject.toml:version"]
branch = "main"
commit = true
tag = true
changelog = true
changelog_file = "CHANGELOG.md"

Woodpecker CI在main分支的配置：

pipeline:
  test:
    image: python:3.11
    commands:
      - pip install -r requirements.txt
      - pytest --cov=./src
  release:
    image: python:3.11
    environment:
      - GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }}
    commands:
      - pip install python-semantic-release
      - semantic-release version  # 计算正式版本号并更新配置文件
      - semantic-release publish  # 生成变更日志、推送标签、发布正式镜像
    when:
      branch: main
      event: push  # 仅在合并到main时触发

3. 解答你的疑问 #

（1）分支结构与CI配置的正确设计 #

就是上面提到的dev→release/x.y→main流程：dev做日常开发，release分支专门处理RC版本（只生成镜像，不修改Git），main分支做正式发布统一生成变更日志。这个流程既满足了测试需求，又能保证正式版本的变更日志是分组展示的。

（2）semantic-release的运行分支策略 #

• main分支必须运行完整的semantic-release（生成版本、变更日志、标签、推送Git变更）
• release/*分支只运行semantic-release的版本计算和制品发布部分，禁止修改Git仓库内容（通过commit=false和tag=false配置）
• dev分支不需要运行semantic-release，用SHA做部署标识即可

（3）测试部署的处理方式 #

• dev分支用dev-<SHA>镜像：适合日常快速测试单个功能
• release/*分支用RC版本镜像（如v2.1.0-rc.1）：适合针对即将发布的完整版本做集成测试
  这样既保留了规范的版本标识，又不会影响正式发布的变更日志分组。

（4）是否误用了semantic-release？ #

你并没有误用，只是没完全掌握它的「提交消耗」逻辑——semantic-release会通过最后一次版本标签或LAST_RELEASE环境变量记录已处理的提交，所以预发布阶段不能让它修改Git历史，否则正式发布时就无法扫描到所有未处理的提交。上面的方案就是避开这个问题，让RC阶段只利用它的版本计算能力，不触碰Git仓库。

额外注意事项 #

• 必须严格执行约定式提交规范，确保semantic-release能正确识别feat/fix/chore等类型的提交
• 合并release/x.y到main时，一定要用普通merge，禁止squash或rebase，否则semantic-release会丢失提交历史，导致版本计算错误
• Woodpecker CI的权限配置要区分：release分支的semantic-release不需要Git推送权限，main分支的需要配置Git仓库的访问令牌

内容的提问来源于stack exchange，提问作者AK-23