Jenkins脚本如何获取构建触发原因

本文目录导读：

1. 使用 currentBuild 对象（推荐，适用于任何 Pipeline）
2. 使用 cause 变量（系统 Groovy 脚本）
3. 在 Pipeline 中使用环境变量（简单但有限）
4. 处理常用的触发原因类型
5. 总结建议

在Jenkins脚本（无论是Pipeline脚本还是系统脚本）中，获取构建触发原因的方法有很多种，具体取决于你使用的脚本类型（Declarative Pipeline、Scripted Pipeline 或 Groovy脚本）。

以下是几种常见的获取方式：

使用 currentBuild 对象（推荐，适用于任何 Pipeline）

这是最直接、最常用的方法。currentBuild 是一个全局变量,包含了当前构建的几乎所有信息。

// Declarative Pipeline 或 Scripted Pipeline 中均可使用
pipeline {
    agent any
    stages {
        stage('Check Trigger Cause') {
            steps {
                script {
                    // 获取触发原因对象
                    def cause = currentBuild.getBuildCauses()
                    echo "Trigger Causes: ${cause}"
                    // 更详细的分类获取
                    def upstreamCause = currentBuild.getBuildCauses('hudson.model.Cause$UpstreamCause')
                    def userCause = currentBuild.getBuildCauses('hudson.model.Cause$UserIdCause')
                    def timerCause = currentBuild.getBuildCauses('hudson.triggers.TimerTrigger$TimerTriggerCause')
                    if (upstreamCause) {
                        echo "触发原因: 上游项目构建完成 (Project: ${upstreamCause[0].upstreamProject}, Build: ${upstreamCause[0].upstreamBuild})"
                    } else if (userCause) {
                        echo "触发原因: 用户手动触发 (User: ${userCause[0].userId})"
                    } else if (timerCause) {
                        echo "触发原因: 定时触发器 (Timer Trigger)"
                    } else {
                        echo "触发原因: 其他 (${cause})"
                    }
                }
            }
        }
    }
}

使用 cause 变量（系统 Groovy 脚本）

如果你在 Jenkins 的 “系统管理” -> “脚本控制台” 中运行脚本，可以直接操作 Jenkins 对象模型：

// 脚本控制台中使用
def job = Jenkins.instance.getItemByFullName("你的任务名称")
def build = job.getLastBuild()
def causes = build.getCauses()
causes.each { cause ->
    println "触发原因类型: ${cause.class.name}"
    println "触发原因描述: ${cause.getShortDescription()}"
    // 判断具体类型
    if (cause instanceof hudson.model.Cause$UserIdCause) {
        println "  用户: ${cause.userId}"
    } else if (cause instanceof hudson.model.Cause$UpstreamCause) {
        println "  上游项目: ${cause.upstreamProject}"
    } else if (cause instanceof hudson.triggers.TimerTrigger$TimerTriggerCause) {
        println "  定时触发"
    }
}

在 Pipeline 中使用环境变量（简单但有限）

Jenkins 提供了几个环境变量可以帮助快速判断触发原因：

• BUILD_CAUSE：包含触发原因的简短描述（如 MANUALTRIGGER、TIMERTRIGGER、UPSTREAMTRIGGER）。
• BUILD_CAUSE_<类型>：针对特定触发器的变量，BUILD_CAUSE_MANUALTRIGGER=true。

pipeline {
    agent any
    stages {
        stage('Check Environment Variables') {
            steps {
                script {
                    // 环境变量方式（简单判断）
                    if (env.BUILD_CAUSE == 'MANUALTRIGGER') {
                        echo "手动触发"
                    } else if (env.BUILD_CAUSE == 'TIMERTRIGGER') {
                        echo "定时触发"
                    } else if (env.BUILD_CAUSE == 'UPSTREAMTRIGGER') {
                        echo "上游触发"
                    } else {
                        echo "其他触发: ${env.BUILD_CAUSE}"
                    }
                    // 或直接检查特定变量是否存在
                    if (env.BUILD_CAUSE_MANUALTRIGGER) {
                        echo "由用户手动触发"
                    }
                }
            }
        }
    }
}

缺点：环境变量的信息有限,无法获取详细的上游项目名或触发用户ID。

处理常用的触发原因类型

以下是最常见的触发原因及其对应的Java类名（在Groovy中可用）：

示例：判断 GitLab Webhook 触发

def gitLabCause = currentBuild.getBuildCauses('com.dabsquared.gitlabjenkins.GitLabPushTrigger')
if (gitLabCause) {
    echo "由 GitLab Webhook 触发"
    echo "源分支: ${gitLabCause[0].sourceBranch}"
    echo "提交信息: ${gitLabCause[0].lastCommitMessage}"
}

总结建议

• 大部分场景：使用 currentBuild.getBuildCauses('具体类名') 最灵活可靠。
• 快速简单判断：使用环境变量 env.BUILD_CAUSE。
• 获取详细信息（如触发用户、上游项目名称）：必须使用 getBuildCauses() 并解析对象。

注意：如果是 Declarative Pipeline，需要将复杂逻辑放在 script { } 块中；如果是 Scripted Pipeline,可以直接写。