Jenkins 流水线中设置阶段状态

1. 概述

Jenkins 流水线会报告构建和阶段的状态，以反映其成功或失败。这种机制对于通知团队成员构建状态非常有用，也间接反映了代码的稳定性。

在某些场景下，我们可能需要手动设置某个阶段的状态，而不管其实际执行结果如何。例如，某个步骤执行的命令并不关键，我们不希望它失败时导致整个构建失败。这时，我们就可以忽略该步骤结果，将阶段或构建状态强制设为 SUCCESS。

本篇文章将介绍 Jenkins 流水线中“阶段”的概念及其状态类型，同时演示如何手动设置阶段状态。

2. 什么是流水线阶段（Pipeline Stage）

流水线阶段表示软件交付流程中的特定阶段。例如，我们可以有“构建”、“测试”、“部署”等阶段，这些阶段串联起来构成完整的 CI/CD 流程。

每个阶段中包含若干步骤（steps），用于实现该阶段的目标。例如，执行命令、复制文件、部署制品等。下面是一个包含多个阶段的 Jenkins 流水线示例：

pipeline {
    agent any
    stages {
        stage("clone repo") {
            steps {
                git branch: "main", url: "https://github.com/spring-projects/spring-petclinic.git"
            }
        }
        stage("build") {
            steps {
                sh "mvn compile"
            }
        }
        stage("test") {
            steps {
                sh "mvn test"
            }
        }
    }
}

在这个例子中，我们定义了三个阶段：克隆仓库、构建、测试。每个阶段都包含具体的步骤，结构清晰，易于理解。

3. 阶段状态（Stage Status）

在流水线执行过程中，每个阶段都会报告其状态。阶段状态代表该阶段内步骤执行的结果。下面是常见的 Jenkins 阶段状态及其含义。

3.1. SUCCESS

顾名思义，SUCCESS 表示该阶段内所有步骤均执行成功。如果步骤中包含命令执行，所有命令都必须返回退出码 0。

示例：

pipeline {
    agent any
    stages {
        stage("Success") {
            steps {
                sh "exit 0"
                sh "ls -l"
            }
        }
    }
}

执行结果如下图所示，阶段显示绿色 ✅，表示成功：

jenkins success stage

3.2. FAILED

FAILED 表示阶段中至少有一个步骤执行失败。若步骤中执行了命令，只要有一个命令返回非 0 退出码，阶段状态即为 FAILED。

示例：

pipeline {
    agent any
    stages {
        stage("Success") {
            steps {
                sh "exit 0"
                sh "ls -l"
            }
        }
        stage("Fail") {
            steps {
                sh "ls -l"
                sh "exit 1"
            }
        }
    }
}

执行后阶段显示红色 ❌，表示失败：

jenkins failed stage

3.3. UNSTABLE

UNSTABLE 状态表示发生了非致命错误。比如，某个非关键步骤失败，但我们仍希望流水线继续执行下去。

我们可以通过 warnError 步骤来实现这一点：

pipeline {
    agent any
    stages {
        stage("Unstable") {
            steps {
                warnError("命令执行失败") {
                    sh "Wrong command"
                }
            }
        }
        stage("Continue execution") {
            steps {
                sh "exit 0"
            }
        }
    }
}

执行结果如下图，阶段显示黄色 ⚠️，表示状态为 UNSTABLE，但后续阶段仍继续执行：

jenkins unstable stage

4. 手动设置阶段状态

Jenkins 允许我们手动控制阶段状态，即使该阶段实际执行失败，我们也可以将其标记为成功或其他状态。这是非常实用的功能，尤其适用于非关键步骤。

我们可以通过 Jenkins 提供的 catchError 步骤来实现。

4.1. 设置为 SUCCESS

示例代码如下：

pipeline {
    agent any
    stages {
        stage("Set Stage Status") {
            steps {
                catchError(buildResult: 'SUCCESS', stageResult: 'SUCCESS') {
                    sh "exit 1"
                }
            }
        }
        stage("Continue execution") {
            steps {
                sh "exit 0"
            }
        }
    }
}

执行后阶段显示绿色 ✅，即使命令返回了非 0 退出码：

set stage status

控制台输出如下图所示，虽然有错误，但状态仍为 SUCCESS：

set stage status in jenkins

4.2. 设置为 UNSTABLE

同样，我们也可以将其设置为 UNSTABLE：

catchError(buildResult: 'UNSTABLE', stageResult: 'UNSTABLE') {
    sh "exit 1"
}

执行后阶段显示黄色 ⚠️，控制台也报告状态为 UNSTABLE：

set unstable status

5. 总结

本文介绍了 Jenkins 流水线中阶段的概念及其状态类型：

✅ SUCCESS：所有步骤执行成功
❌ FAILED：至少有一个步骤执行失败
⚠️ UNSTABLE：发生非致命错误，但仍可继续执行

并通过 catchError 步骤演示了如何手动设置阶段状态，即使步骤执行失败，也可以控制其显示为 SUCCESS 或 UNSTABLE。

✅ 适用场景：

非关键性步骤（如日志上传、清理任务）失败时不影响主流程
多阶段测试中某个测试失败但不影响部署
构建报告生成失败但不希望整个构建失败

这种机制非常灵活，适合在 CI/CD 中精细化控制构建流程。

Persistence

REST

Security