Jenkins Bitbucket项目报GitChangeSetList序列化异常排查咨询

遇到这种java.io.NotSerializableException: hudson.plugins.git.GitChangeSetList的问题确实闹心，尤其是从偶现变必现，还没主动碰过这个对象对吧？我帮你梳理几个核心排查方向，都是流水线序列化问题的常见坑：

Jenkins流水线的底层依赖序列化机制来保存上下文状态（比如跨节点执行、重启恢复），而GitChangeSetList这个类本身不支持序列化——只要它被意外留在了流水线的全局上下文里，就会触发这个异常。以下是具体排查点：

1. 检查是否隐式捕获了GitChangeSetList到全局变量 #

很多时候我们会无意间把变更集对象赋值给全局变量，比如在pipeline{}块外面定义的变量，或者在stage外部的脚本块里赋值。举个典型的错误例子：

// 错误写法：全局变量持有不可序列化的GitChangeSetList
def globalChanges
pipeline {
    agent any
    stages {
        stage('Check Changes') {
            steps {
                script {
                    globalChanges = currentBuild.changeSets // 这个对象被留在了全局上下文
                }
            }
        }
    }
}

修复方式：确保所有涉及currentBuild.changeSets或scm.changeSets的变量都是局部变量，只在script{}块内部使用，用完就销毁：

// 正确写法：仅在局部处理变更集
pipeline {
    agent any
    stages {
        stage('Check Changes') {
            steps {
                script {
                    def localChanges = currentBuild.changeSets
                    // 在这里完成所有变更集处理，比如遍历提交信息
                    localChanges.each { changeSet ->
                        changeSet.each { commit ->
                            echo "Commit ID: ${commit.id} | Message: ${commit.msg}"
                        }
                    }
                }
            }
        }
    }
}

2. 检查共享库是否留下了非序列化对象 #

如果你的流水线用到了自定义共享库，要警惕库中的方法是否返回或持有GitChangeSetList对象——一旦这个对象被传递回主流水线上下文，就会触发序列化失败。
修复方式：在共享库中只返回可序列化的类型（比如字符串列表、Map），或者用@NonCPS注解标记处理逻辑（@NonCPS块内的代码不会被序列化，但注意不能和流水线步骤混用）：

// 共享库中的正确写法：提取需要的信息返回
@NonCPS
def getCommitMessages() {
    def messages = []
    currentBuild.changeSets.each { changeSet ->
        changeSet.each { commit ->
            messages.add(commit.msg)
        }
    }
    return messages
}

3. 排查插件或流水线扩展的隐式影响 #

有些第三方插件（尤其是变更日志、流水线增强类的）可能会在后台把GitChangeSetList添加到流水线上下文里。另外，post阶段的某些步骤也可能间接引用到这个对象。
排查步骤：

• 暂时禁用最近新增的插件，尤其是和Git变更、流水线状态相关的，看是否恢复正常。
• 简化流水线到最简状态（只保留checkout和基础步骤），如果正常，再逐步添加原有步骤，定位到哪个环节引入的问题。
• 检查post阶段的代码，比如是否有archiveArtifacts或其他步骤无意中关联了变更集对象。

4. 检查Jenkins与Git插件的版本兼容性 #

从偶现变必现，很可能是插件版本更新导致的——比如Git插件的某次更新改变了GitChangeSetList的序列化行为，或者和Jenkins核心版本不兼容。
排查步骤：

• 查看Git插件的更新日志，确认最近是否有关于序列化或GitChangeSetList的变更。
• 尝试回退Git插件到之前偶现时期的版本，看问题是否消失。
• 确保Jenkins核心版本和Git插件版本是官方推荐的兼容组合。

5. 启用序列化调试日志定位根源 #

如果上面的方法都没找到问题，可以开启Jenkins的序列化调试日志，精准定位哪个对象持有了GitChangeSetList：

1. 进入Jenkins后台的Manage Jenkins > System Log > Add new log recorder。
2. 新建一个日志记录器（比如命名为Pipeline Serialization）。
3. 添加两个日志级别配置：org.jenkinsci.plugins.workflow设为DEBUG，hudson.plugins.git设为DEBUG。
4. 重新运行失败的流水线，查看日志中关于序列化的详细输出，就能找到触发异常的对象链条。

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