Azure DevOps发布管道执行mvn release:prepare报git HEAD非符号引用错误

问题原因 #

这个错误的核心是当前Git处于 detached HEAD 状态——Maven Release插件需要在一个分支（符号引用）上执行版本变更、提交操作，而不是直接指向某个单独的commit。Azure DevOps默认的checkout任务有时会拉取特定commit而非完整分支，导致HEAD脱离分支。

解决方案 #

• 调整Git Checkout步骤：
  在Azure DevOps发布管道的Checkout任务中，确保拉取的是完整分支而非单个commit。可以在任务设置里选择Checkout a specific branch，指定你的目标分支（如main/master）；或者在YAML管道中添加：

  steps:
  - checkout: self
    fetchDepth: 0
    ref: refs/heads/main
  

  fetchDepth: 0会拉取完整仓库历史，避免浅克隆导致的分支信息缺失。

• 显式切换到目标分支：
  如果checkout后仍处于detached状态，在执行Maven命令前添加Git切换分支的脚本：

  git checkout main
  

  替换main为你的实际分支名，确保HEAD指向分支引用。

• 验证SCM配置与权限：
  确认pom.xml的SCM配置正确，例如：

  • HTTPS格式：

    <scm>
      <connection>scm:git:https://dev.azure.com/[组织名]/[项目名]/_git/[仓库名]</connection>
      <developerConnection>scm:git:https://dev.azure.com/[组织名]/[项目名]/_git/[仓库名]</developerConnection>
    </scm>
    

  • SSH格式：

    <scm>
      <connection>scm:git:git@ssh.dev.azure.com:v3/[组织名]/[项目名]/[仓库名]</connection>
      <developerConnection>scm:git:git@ssh.dev.azure.com:v3/[组织名]/[项目名]/[仓库名]</developerConnection>
    </scm>
    

  同时确保Azure DevOps的服务连接拥有仓库的Contributor权限，允许Maven提交版本变更。

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