为何在GitHub Actions中使用GitVersion时补丁版本不递增？

我在GitHub Actions中针对main分支使用GitVersion工具。推送v2.0.0这类新标签到main分支后，期望补丁版本按2.0.0, 2.0.1, 2.0.2, ...的规则递增。但实际情况是，推送v2.0.0标签后，首次向main分支推送代码得到版本2.0.1，但后续每次推送代码，生成的版本始终停留在2.0.1，补丁版本没有随每次推送递增。

我的配置 #

GitHub工作流配置 #

name: Project
    
on:
  push:
    branches: [ main ]

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.versioning.outputs.semVer }}
    name: setup
    steps: 
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Dotnet
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.x'
 
      - name: GitVersion
        uses: gittools/actions/gitversion/setup@v1
        with:
          versionSpec: '5.x'

      - name: Versioning
        uses: gittools/actions/gitversion/execute@v1
        id: versioning
          
  build:
      // Remaining workflow code

gitversion.yml配置 #

mode: Mainline
branches:
  main:
    regex: ^main$
    mode: Mainline
    increment: Patch
    is-mainline: true

项目根目录已正确放置gitversion.yml文件。

原因分析 #

问题源于GitVersion的Mainline模式逻辑：

• 当推送v2.0.0标签后，GitVersion会将该标签对应的提交设为版本基线。
• Mainline模式默认设计用于"通过合并请求向main分支引入变更"的工作流，只有合并PR的提交才会被视为版本递增的触发点。
• 直接向main分支推送的提交，GitVersion会将其视为同一批次的未合并变更，仅在首次推送时递增一次补丁版本，后续推送不会重复递增。

解决方案 #

方案1：切换到ContinuousDeployment模式（推荐直接提交场景） #

修改gitversion.yml，改用更适合直接向main分支提交的模式：

mode: ContinuousDeployment
branches:
  main:
    regex: ^main$
    increment: Patch
    tag: '' # 禁用自动标签，保留手动打标签的流程

该模式会为main分支的每一次新提交递增补丁版本。

方案2：坚持使用Mainline模式 #

调整工作流，所有main分支的变更必须通过合并请求（PR）合并，而非直接推送。GitVersion会在每次PR合并时自动递增补丁版本。

方案3：提交信息标记强制递增 #

在提交信息中添加+semver:patch标记，强制GitVersion递增补丁版本，示例：

fix: 修复用户中心数据展示问题 +semver:patch

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