How to Use currentBuild in Jenkins Pipeline

In Jenkins Pipeline, currentBuild is a global variable that gives you access to the current build's information and status. You can use it to get or set the build result, display build details, or add descriptions dynamically within your pipeline script.

Syntax

The currentBuild variable provides properties and methods to interact with the current build. Common properties include:

• currentBuild.result: Get or set the build status (e.g., 'SUCCESS', 'FAILURE').
• currentBuild.displayName: Set a custom name for the build.
• currentBuild.description: Add a description visible in the build page.
• currentBuild.number: The build number.

You use it directly in your pipeline script without needing to declare it.

groovy

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                script {
                    // Set build result
                    currentBuild.result = 'SUCCESS'
                    // Set display name
                    currentBuild.displayName = "Build #${currentBuild.number} - Custom"
                    // Add description
                    currentBuild.description = 'This build passed all tests.'
                }
            }
        }
    }
}

Example

This example shows how to use currentBuild to set the build result based on a condition and add a description dynamically.

groovy

pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                script {
                    def testPassed = true
                    if (testPassed) {
                        currentBuild.result = 'SUCCESS'
                        currentBuild.description = 'Tests passed successfully.'
                    } else {
                        currentBuild.result = 'FAILURE'
                        currentBuild.description = 'Tests failed.'
                    }
                    currentBuild.displayName = "Build #${currentBuild.number} - ${currentBuild.result}"
                }
            }
        }
    }
}

Output

Build #15 - SUCCESS
Description: Tests passed successfully.

Common Pitfalls

Some common mistakes when using currentBuild include:

• Trying to set currentBuild.result to invalid values (only 'SUCCESS', 'FAILURE', 'UNSTABLE', 'ABORTED' are valid).
• Setting currentBuild.result too late in the pipeline, which may not affect the final build status.
• Using currentBuild outside of script blocks in declarative pipelines, causing errors.

groovy

pipeline {
    agent any
    stages {
        stage('Wrong Usage') {
            steps {
                // This will cause an error because currentBuild usage requires script block
                script {
                    currentBuild.result = 'SUCCESS'
                }
            }
        }
        stage('Correct Usage') {
            steps {
                script {
                    currentBuild.result = 'SUCCESS'
                }
            }
        }
    }
}

Quick Reference

Property/Method	Description	Example Value
currentBuild.result	Get or set the build status	'SUCCESS', 'FAILURE', 'UNSTABLE', 'ABORTED'
currentBuild.displayName	Set a custom build name	"Build #15 - SUCCESS"
currentBuild.description	Add a description to the build	"Tests passed successfully."
currentBuild.number	Get the current build number	15

Key Takeaways

Use currentBuild inside script blocks in declarative pipelines.

Set currentBuild.result early to control build status effectively.

You can customize build name and description dynamically with currentBuild.displayName and currentBuild.description.

Valid build results are 'SUCCESS', 'FAILURE', 'UNSTABLE', and 'ABORTED'.

Access currentBuild.number to get the current build's number.