Jenkins多分支任务部分从Master衍生的分支构建失败求助

我之前遇到过几乎一模一样的问题，折腾了好几天，下面是我总结的几个排查方向和解决办法，你可以逐个试试：

1. 先排查分支命名的坑 #

首先检查那些出问题的分支名称：

• 有没有和仓库里的tag重名？比如你有个tag叫hotfix/v1.0，同时又建了一个同名分支，Jenkins多分支扫描时会混淆tag和分支，导致无法正确定位分支的tip版本。
• 有没有包含特殊字符？比如空格、中文、或者过多的斜杠？虽然Git支持，但Jenkins的SCMBinder对某些特殊字符的解析可能有bug。

对比一下正常构建的分支和问题分支的命名差异，试着把问题分支重命名（比如改成bugfix/test-123这种简单格式），然后重新推送，再触发Jenkins扫描，看能不能正常构建。

2. 清理Jenkins的分支缓存和工作区 #

Jenkins多分支流水线有时候会缓存旧的分支信息，导致新分支或修改后的分支无法正确识别：

• 进入你的多分支流水线项目页面，找到出问题的分支，点击右侧的删除按钮，把它从Jenkins里移除。
• 然后点击项目页面的重新扫描多分支流水线按钮，让Jenkins重新识别分支并拉取最新代码。
• 如果还是不行，可以登录Jenkins节点（主节点或对应的从节点），找到该分支的工作区目录，手动删除整个文件夹，再重新触发构建。

3. 关闭"轻量检出"选项 #

很多时候这个选项是罪魁祸首：

• 进入多分支流水线的配置页面，找到Branch Sources里的Git配置，展开Advanced选项。
• 取消勾选Lightweight checkout（轻量检出），保存配置后重新扫描分支。

轻量检出只会拉取必要的元数据，不会完整克隆仓库，当分支有特殊的历史（比如rebase、force push后的分支），很容易导致Jenkins无法确定分支的精确tip版本，进而出现detached HEAD的问题。

4. 在流水线脚本里显式指定Checkout步骤 #

如果依赖SCM自动绑定还是有问题，可以在你的Jenkinsfile里手动写checkout逻辑，强制指定分支：

pipeline {
    agent any
    stages {
        stage('Checkout Code') {
            steps {
                checkout([
                    $class: 'GitSCM',
                    branches: [[name: "*/${env.BRANCH_NAME}"]],
                    userRemoteConfigs: [[
                        url: '你的GitLab仓库地址',
                        credentialsId: '你的GitLab凭据ID'
                    ]],
                    extensions: [[$class: 'CleanCheckout']] // 每次构建都清理工作区
                ])
            }
        }
        // 其他构建步骤...
    }
}

这个方法跳过了SCMBinder的自动识别，直接指定拉取当前分支的代码，很多时候能解决detached HEAD的问题。

5. 检查Git插件的兼容性 #

虽然你已经升级了Jenkins和插件，但有时候新版本的Git插件或Pipeline Multibranch插件会有兼容性问题：

• 可以尝试降级Git插件到之前稳定的版本（比如你之前正常运行时的版本），或者降级Pipeline Multibranch插件，再测试构建。
• 另外，确保Jenkins节点上的Git客户端版本是最新的，旧版本的Git可能和新插件不兼容。

6. 排查分支的提交历史 #

虽然你说本地克隆正常，但还是可以检查一下问题分支的提交：

• 在GitLab上查看问题分支的提交历史，确认最新的提交是存在的，并且没有被force push覆盖。
• 在Jenkins节点上手动执行命令，测试能不能正确拉取分支：

git fetch origin your-branch-name
git checkout your-branch-name
git status

如果手动执行没问题，但Jenkins构建还是出问题，那大概率是Jenkins的配置或插件问题。

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