Marking Shell Script Builds as Unstable in Jenkins Using the Text-finder Plugin

Introduction

In continuous integration and continuous deployment (CI/CD) workflows, Jenkins, as a widely used automation server, relies on accurate build status marking for team collaboration and issue tracking. According to Jenkins terminology, build statuses are typically categorized into success, failure, and unstable. Success indicates error-free completion; failure denotes fatal errors during the build; and unstable status means the build completed successfully but detected non-critical issues, such as test failures, requiring further attention.

Problem Context

In real-world projects, developers often use Shell or PHP scripts to execute various tasks, such as file synchronization (e.g., using rsync commands) or running integration tests. These scripts typically control Jenkins build results through exit status codes. For example, in PHP scripts, if test failures are detected, the script exits with code 1, causing Jenkins to mark the build as failed. However, in some scenarios, test failures might be considered non-critical and better marked as unstable to avoid disrupting the entire build process while alerting the team for fixes.

Consider the following PHP script example, where exit code 1 indicates a build error:

// :: End of PHP script:
// If any tests have failed, fail the build
if ($build_error) exit(1);

This approach, while simple, only distinguishes between success and failure states and cannot achieve unstable marking. Therefore, more flexible solutions need to be explored.

Core Solution: Using the Text-finder Plugin

The Text-finder plugin offers an elegant way to address this issue. It allows searching for specific text patterns in build output and adjusting build status based on matches. Below is a detailed explanation of the implementation steps.

Step 1: Modify Script Output

First, in Shell or PHP scripts, avoid using exit code 1 to directly mark build failure. Instead, when non-critical errors (e.g., test failures) are detected, output a specific string. For example, in a PHP script, modify as follows:

if ($build_error) print("TESTS FAILED!");

Here, print("TESTS FAILED!") prints the string TESTS FAILED! to standard output, while the script still exits with code 0, thus not causing build failure. This ensures the build process completes technically successfully but conveys error information via output strings.

Step 2: Configure the Text-finder Plugin

In the post-build actions of a Jenkins job, enable the Text Finder plugin. Configure as follows:

• Regular Expression: Set to match the string output by the script, e.g., TESTS FAILED!. The regex should accurately capture the target text to avoid false matches.
• Options: Check the "Unstable if found" checkbox. This instructs Jenkins to mark the build as unstable when matching text is found.

With this configuration, when the script output contains TESTS FAILED!, the Text-finder plugin detects the string and sets the build result to unstable. This method does not rely on exit codes, offering greater flexibility to dynamically adjust status based on output content.

Step 3: Testing and Validation

Run the Jenkins job to verify the configuration. If the script outputs TESTS FAILED!, the build log should show Text-finder plugin matches, and the build status should be marked unstable. Check the build history via the Jenkins interface or use APIs to inspect status. Ensure the regular expression is correct to avoid match failures due to formatting issues.

Comparison with Other Methods

Beyond the Text-finder plugin, other methods can achieve similar functionality, each with pros and cons.

Method 1: Jenkins CLI

Using the Jenkins Command Line Interface (CLI), build status can be set directly. For example, in a Shell script, execute:

java -jar jenkins-cli.jar set-build-result unstable

This requires the jenkins-cli.jar file in the script environment, achievable via download or pre-configured paths. However, this method adds dependencies and complexity, may not suit all environments, and requires handling CLI authentication and network issues.

Method 2: Jenkinsfile and Pipeline

For Jenkins jobs using Pipeline, build status can be set directly in scripts via Jenkinsfile. Example code:

stage {
    status = /* your build command */
    if (status === "MARK-AS-UNSTABLE") {
        currentBuild.result = "UNSTABLE"
    }
}

This method is more modern, suitable for code-based CI/CD workflows, but requires jobs configured as Pipeline type and familiarity with Groovy syntax.

Method 3: Advanced Shell Options

In newer Jenkins versions (e.g., 2.26 and above), the Execute Shell build step offers advanced options to set specific exit codes for marking builds unstable. Users can choose an uncommon exit code (e.g., 13) and return it in scripts. But this method depends on Jenkins version and may conflict with exit codes from other processes.

Best Practices Recommendations

Based on the above analysis, the following best practices are recommended:

1. Prioritize the Text-finder Plugin: For most scenarios, the Text-finder plugin provides a simple, non-intrusive solution. It does not modify core script logic, achieving status marking only through output strings and regex matching, making it easy to maintain and debug.
2. Standardize Error Output Format: Standardize error strings within the team, e.g., using prefixes like [ERROR], to facilitate Text-finder configuration and log analysis. This enhances readability and consistency.
3. Combine Multiple Methods: In complex projects, consider mixing Text-finder and Jenkinsfile, selecting the most appropriate method per task. For example, use Text-finder for Shell scripts and currentBuild.result for Pipeline jobs.
4. Test and Monitor: Regularly test build status marking functionality to ensure unstable status correctly triggers notifications (e.g., emails or Slack messages). Monitor build history to analyze causes of unstable builds and improve code quality.

Conclusion

Marking Shell script builds as unstable in Jenkins is a key aspect of optimizing CI/CD workflows. By using the Text-finder plugin, developers can flexibly control build status based on script output without relying on exit codes or complex external tools. This article details the implementation steps of this method and compares alternative solutions, offering comprehensive guidance for practical applications. As DevOps practices become widespread, properly handling build statuses will help enhance team efficiency and software quality.