currentBuild variables in Jenkins - Deep Dive

Overview - currentBuild variables

What is it?

In Jenkins pipelines, currentBuild variables provide information about the current running build. These variables let you access details like build status, duration, and result during the pipeline execution. They help you understand and control the build process dynamically. This makes your automation smarter and more responsive.

Why it matters

Without currentBuild variables, you would not know the state or outcome of your build while it runs. This would make it hard to react to failures, send notifications, or make decisions based on build progress. Using these variables improves automation reliability and feedback speed, saving time and reducing errors.

Where it fits

Before learning currentBuild variables, you should understand Jenkins pipelines and basic Groovy scripting. After this, you can explore advanced pipeline features like post-build actions, notifications, and custom build logic that depend on build state.

Mental Model

Core Idea

currentBuild variables are like a live dashboard showing the current build’s status and details inside your Jenkins pipeline.

Think of it like...

Imagine you are driving a car and the dashboard shows your speed, fuel level, and engine warnings in real-time. currentBuild variables are the Jenkins pipeline’s dashboard, showing what’s happening with the build as it runs.

┌─────────────────────────────┐
│        currentBuild          │
├─────────────┬───────────────┤
│ Variable    │ Description   │
├─────────────┼───────────────┤
│ result      │ Build result  │
│ duration    │ Build time ms │
│ displayName │ Build name    │
│ description │ Build notes   │
│ fullDisplayName │ Full build name │
│ id          │ Build ID      │
│ number      │ Build number  │
│ previousBuild │ Previous build│
│ rawBuild    │ Internal build│
└─────────────┴───────────────┘

Build-Up - 6 Steps

1

Foundation

What is currentBuild in Jenkins

Concept: Introduce currentBuild as a special variable in Jenkins pipeline scripts.

In Jenkins scripted or declarative pipelines, currentBuild is a global variable that holds information about the build currently running. You can access it directly in your pipeline code to get details like build number or status.

Result

You can write code like `echo currentBuild.number` to print the current build number.

Understanding currentBuild as a built-in object lets you tap into live build data without extra setup.

2

Foundation

Basic currentBuild properties explained

Concept: Learn the most common properties of currentBuild and what they mean.

Some key properties are: - result: The build result (e.g., SUCCESS, FAILURE) - duration: How long the build has run in milliseconds - displayName: The name shown in Jenkins UI - number: The build number - previousBuild: Reference to the previous build object You can print these to see their values during a build.

Result

Printing `currentBuild.result` might show 'SUCCESS' if the build passed.

Knowing these properties helps you monitor and react to build status dynamically.

3

Intermediate

Using currentBuild to control pipeline flow

🤔Before reading on: do you think you can change pipeline steps based on currentBuild.result? Commit to yes or no.

Concept: Use currentBuild properties to make decisions in your pipeline script.

You can write conditional logic like: ``` if (currentBuild.result == 'FAILURE') { echo 'Build failed, sending alert' } ``` This lets your pipeline react to its own status, for example, sending notifications only on failure.

Result

The pipeline can skip or add steps depending on the build result.

Using currentBuild for flow control makes pipelines smarter and more efficient.

4

Intermediate

Accessing previousBuild via currentBuild

🤔Before reading on: do you think previousBuild is always available? Commit to yes or no.

Concept: Learn how to get information about the last build using currentBuild.previousBuild.

currentBuild.previousBuild gives you the build object before the current one. You can check its result or duration: ``` if (currentBuild.previousBuild?.result == 'FAILURE') { echo 'Previous build failed' } ``` The question mark avoids errors if no previous build exists.

Result

You can compare current and previous builds to detect trends or repeated failures.

Knowing how to safely access previousBuild prevents pipeline crashes and enables build history awareness.

5

Advanced

Modifying currentBuild description dynamically

🤔Before reading on: can you update currentBuild.description during a build? Commit to yes or no.

Concept: You can set or change the build description to add useful info visible in Jenkins UI.

Use `currentBuild.description = 'Deployed to staging'` inside your pipeline to update the build’s description. This helps track what happened in that build without checking logs.

Result

The Jenkins UI shows the updated description for the build.

Updating build metadata dynamically improves build traceability and team communication.

6

Expert

Understanding currentBuild.rawBuild internals

🤔Before reading on: do you think rawBuild is a simple string or a complex object? Commit to your answer.

Concept: rawBuild is the internal Jenkins object behind currentBuild, exposing advanced APIs.

currentBuild.rawBuild gives access to the Jenkins core Run object. This lets you call advanced methods not exposed by currentBuild, like getting build causes or artifacts: ``` def causes = currentBuild.rawBuild.getCauses() ``` Use this carefully as it ties your pipeline to Jenkins internals.

Result

You can access deep build details and customize behavior beyond standard properties.

Knowing rawBuild unlocks powerful Jenkins internals but requires caution to avoid breaking pipelines on Jenkins upgrades.

Under the Hood

currentBuild is a Groovy object injected by Jenkins pipeline runtime. It wraps the Jenkins Run object representing the build. Properties like result or duration are fetched live from this Run object. When you access currentBuild in your pipeline, Jenkins translates it to calls on the underlying Run instance, providing up-to-date build info.

Why designed this way?

Jenkins pipelines needed a simple way to access build info without complex API calls. Wrapping the Run object in currentBuild provides a clean, Groovy-friendly interface. This design balances ease of use with access to powerful internals via rawBuild, supporting both simple and advanced use cases.

┌───────────────────────────────┐
│ Jenkins Pipeline Runtime       │
│                               │
│  currentBuild (Groovy object) │
│          │                    │
│          ▼                    │
│  Jenkins Run (Java object)    │
│          │                    │
│          ▼                    │
│  Build Data & Metadata        │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does currentBuild.result always have a value during the build? Commit yes or no.

Common Belief: currentBuild.result is always set and reliable during the entire build.

Reality: During the build, currentBuild.result is often null or 'null' until the build finishes or a result is explicitly set.

Why it matters: Assuming result is always set can cause incorrect logic or null pointer errors in pipelines.

Quick: Is currentBuild.previousBuild always available for the first build? Commit yes or no.

Common Belief: previousBuild always points to a valid build object.

Reality: For the very first build, previousBuild is null because no earlier build exists.

Why it matters: Not checking for null can cause pipeline failures on first builds.

Quick: Can you safely modify currentBuild properties like number or id? Commit yes or no.

Common Belief: All currentBuild properties can be changed freely during the build.

Reality: Most properties like number or id are read-only and cannot be changed; only description is safely writable.

Why it matters: Trying to change read-only properties leads to errors or unexpected behavior.

Quick: Is currentBuild.rawBuild a simple string or a complex object? Commit your answer.

Common Belief: rawBuild is just a string or simple data.

Reality: rawBuild is a complex Jenkins internal object exposing advanced APIs and should be used carefully.

Why it matters: Misusing rawBuild can cause pipeline instability and compatibility issues.

Expert Zone

1

currentBuild.result is null until the build finishes or you explicitly set it, so relying on it mid-build requires care.

2

Accessing currentBuild.previousBuild without null checks breaks pipelines on first builds; use safe navigation operators.

3

Using currentBuild.rawBuild ties your pipeline to Jenkins internals, which can change between Jenkins versions, risking pipeline breakage.

When NOT to use

Avoid using currentBuild.rawBuild for simple tasks; prefer standard currentBuild properties to keep pipelines stable. For complex build metadata, consider Jenkins plugins or external tracking systems instead of overloading currentBuild.

Production Patterns

In production, currentBuild is used to set build descriptions dynamically, send conditional notifications on failure, and compare current and previous build results to detect flaky tests or regressions.

Connections

Continuous Integration

currentBuild variables provide live build status essential for CI pipelines.

Understanding currentBuild helps grasp how CI systems monitor and react to build progress in real time.

Event-driven Programming

Using currentBuild to trigger actions based on build state is similar to reacting to events in programming.

Knowing event-driven concepts clarifies how pipelines respond dynamically to build changes.

Real-time Dashboard Systems

currentBuild acts like a real-time dashboard showing live data about the build process.

Understanding real-time dashboards in other fields helps appreciate how currentBuild provides immediate feedback during automation.

Common Pitfalls

#1 Assuming currentBuild.result is set during the build and using it in conditions.

Wrong approach:

if (currentBuild.result == 'FAILURE') {
echo 'Build failed'
}

Correct approach:

if (currentBuild.result == 'FAILURE' || currentBuild.result == null) {
echo 'Build failed or not set yet'
}

Root cause:

currentBuild.result is null until the build finishes or is explicitly set, so checking it too early causes logic errors.

#2 Accessing currentBuild.previousBuild without checking if it exists.

Wrong approach:

if (currentBuild.previousBuild.result == 'FAILURE') {
echo 'Previous build failed'
}

Correct approach:

if (currentBuild.previousBuild?.result == 'FAILURE') {
echo 'Previous build failed'
}

Root cause:

previousBuild is null for the first build, so not checking causes null pointer exceptions.

#3 Trying to change read-only properties like currentBuild.number.

Wrong approach:

currentBuild.number = 100

Correct approach:

currentBuild.description = 'Updated description'

Root cause:

Most currentBuild properties are read-only; only description is writable during the build.

Key Takeaways

currentBuild is a special Jenkins pipeline variable that gives live information about the running build.

Many currentBuild properties like result or previousBuild can be used to make your pipeline smarter and reactive.

Be careful: some properties like result are null until the build finishes, and previousBuild can be null on first builds.

You can update currentBuild.description to add useful notes visible in Jenkins UI during or after the build.

Accessing currentBuild.rawBuild unlocks advanced Jenkins internals but should be done cautiously to avoid pipeline breakage.