Post section (success, failure, always) in Jenkins - Deep Dive

Overview - Post section (success, failure, always)

What is it?

In Jenkins pipelines, the 'post' section defines actions that run after the main pipeline stages finish. It lets you specify tasks to run only when the pipeline succeeds, fails, or always runs regardless of the outcome. This helps automate cleanup, notifications, or other follow-up steps based on the build result.

Why it matters

Without the 'post' section, you would have to manually add repetitive steps in every stage to handle success or failure cases. This would be error-prone and hard to maintain. The 'post' section centralizes these actions, making pipelines more reliable and easier to manage, especially in complex projects.

Where it fits

Before learning the 'post' section, you should understand Jenkins pipeline basics and stages. After mastering it, you can explore advanced pipeline features like parallel stages, scripted pipelines, and shared libraries.

Mental Model

Core Idea

The 'post' section in Jenkins pipelines runs specific steps after the main work, triggered by success, failure, or always, to handle cleanup and notifications automatically.

Think of it like...

It's like finishing a meal and then deciding whether to wash dishes if you enjoyed it, call a friend if it was bad, or always put the table away no matter what happened.

Pipeline
  │
  ├─ Stages (main work)
  │
  └─ Post Section
      ├─ success: run if pipeline succeeded
      ├─ failure: run if pipeline failed
      └─ always: run regardless of result

Build-Up - 7 Steps

1

Foundation

Understanding Jenkins Pipeline Basics

Concept: Learn what a Jenkins pipeline is and how stages define steps.

A Jenkins pipeline is a script that defines a sequence of steps to build, test, and deploy software. It uses 'stages' to group related steps, like 'Build', 'Test', and 'Deploy'. Each stage runs in order.

Result

You can create a simple pipeline with stages that run commands sequentially.

Knowing pipeline basics is essential because the 'post' section attaches to the pipeline lifecycle after these stages.

2

Foundation

Introducing the Post Section

Concept: The 'post' section runs steps after all stages finish.

In a Jenkins pipeline, you add a 'post' block outside the stages. Inside 'post', you define conditions like 'success', 'failure', and 'always' with steps to run after the main work.

Result

You can add a 'post' section that prints messages depending on the pipeline result.

Understanding that 'post' runs after stages helps separate main work from cleanup or notifications.

3

Intermediate

Using the Success Condition

🤔Before reading on: do you think 'success' runs only if all stages pass, or also if some fail? Commit to your answer.

Concept: 'success' runs only when the entire pipeline finishes without errors.

Inside 'post', the 'success' block runs only if all stages complete successfully. For example, sending a success email or archiving artifacts.

Result

Steps inside 'success' execute only on a successful pipeline run.

Knowing 'success' triggers only on full success prevents false notifications or actions.

4

Intermediate

Handling Failures with Failure Condition

🤔Before reading on: does 'failure' run if a stage is unstable or only on hard failure? Commit to your answer.

Concept: 'failure' runs when the pipeline fails due to errors or test failures.

The 'failure' block runs if any stage fails or the pipeline errors out. Use it to send alerts or clean temporary files after failure.

Result

Steps inside 'failure' execute only when the pipeline fails.

Understanding 'failure' helps automate error handling and quick response.

5

Intermediate

Always Condition for Guaranteed Steps

Concept: 'always' runs no matter what the pipeline result is.

The 'always' block runs after the pipeline finishes, regardless of success or failure. It's useful for cleanup tasks like deleting temporary files or stopping services.

Result

Steps inside 'always' execute every time the pipeline ends.

Knowing 'always' ensures critical cleanup or final steps never get skipped.

6

Advanced

Combining Multiple Post Conditions

🤔Before reading on: can you have multiple conditions in one post block, or only one? Commit to your answer.

Concept: You can define multiple conditions in the same 'post' section to handle different outcomes.

A 'post' section can have 'success', 'failure', 'always', and other conditions like 'unstable' or 'changed'. Jenkins runs the matching blocks after the pipeline ends.

Result

Multiple post blocks run selectively based on the pipeline result.

Knowing how to combine conditions lets you tailor responses precisely to pipeline outcomes.

7

Expert

Post Section in Parallel and Scripted Pipelines

🤔Before reading on: does the 'post' section behave the same in scripted pipelines and parallel stages? Commit to your answer.

Concept: The 'post' section works differently in scripted pipelines and with parallel stages, requiring careful placement.

In scripted pipelines, 'post' is less common; you use try-catch-finally blocks instead. For parallel stages, each branch can have its own 'post' section, and the main pipeline 'post' runs after all parallel branches complete.

Result

You can control post actions at different pipeline levels and styles.

Understanding these differences prevents bugs and ensures correct cleanup and notifications in complex pipelines.

Under the Hood

Jenkins pipelines run stages as steps in a Groovy-based DSL. After all stages finish, Jenkins evaluates the pipeline result status. The 'post' section hooks into this final status and triggers the matching blocks. Internally, Jenkins uses listeners to detect pipeline completion and runs the 'post' steps accordingly.

Why designed this way?

The 'post' section was designed to separate main pipeline logic from result-based actions, improving readability and maintainability. It avoids cluttering stages with conditional cleanup or notifications. Alternatives like embedding cleanup in every stage were error-prone and hard to maintain.

Pipeline Start
  │
  ├─ Stage 1
  ├─ Stage 2
  ├─ ...
  └─ Pipeline End
       │
       └─ Evaluate Result ──┬─ success block (if passed)
                            ├─ failure block (if failed)
                            └─ always block (runs always)

Myth Busters - 4 Common Misconceptions

Quick: Does the 'always' block run before or after 'success' and 'failure'? Commit to your answer.

Common Belief: 'always' runs before 'success' and 'failure' blocks.

Reality: 'always' runs after 'success' and 'failure' blocks have executed.

Why it matters: Misunderstanding this order can cause cleanup steps to run too early or notifications to be sent before cleanup, leading to inconsistent pipeline states.

Quick: Does 'failure' run if a stage is marked 'unstable'? Commit to yes or no.

Common Belief: 'failure' runs whenever the pipeline is not fully successful, including unstable stages.

Reality: 'failure' runs only on hard failures; unstable results do not trigger 'failure' but can trigger 'unstable' blocks.

Why it matters: Confusing 'failure' and 'unstable' can cause missed alerts or incorrect handling of test failures.

Quick: Can you use 'post' inside individual stages? Commit to yes or no.

Common Belief: 'post' sections can only be defined at the pipeline level, not inside stages.

Reality: You can define 'post' sections inside individual stages to run stage-specific post actions.

Why it matters: Not knowing this limits pipeline flexibility and leads to duplicated code or missed stage-level cleanup.

Quick: Does the 'post' section run if the pipeline is aborted? Commit to yes or no.

Common Belief: 'post' sections do not run if the pipeline is aborted manually.

Reality: 'post' sections run even if the pipeline is aborted, allowing cleanup and notifications.

Why it matters: Assuming 'post' won't run on abort can cause resource leaks or missing alerts.

Expert Zone

1

The 'post' section can include conditions like 'changed' that run only if the pipeline status changed from the previous run, enabling smart notifications.

2

In declarative pipelines, 'post' blocks can be nested inside stages, allowing fine-grained control over stage-specific post actions.

3

The order of execution inside 'post' blocks matters: 'success' and 'failure' run before 'always', which can affect resource cleanup timing.

When NOT to use

Avoid relying solely on 'post' for complex error handling in scripted pipelines; use try-catch-finally blocks for more control. Also, for very dynamic pipelines, consider shared libraries or external scripts for post-processing.

Production Patterns

In production, teams use 'post' to send Slack notifications on failure, archive build artifacts on success, and always clean up workspace directories. They combine 'post' with environment variables to customize messages and use parallel stage 'post' blocks for branch-specific cleanup.

Connections

Event-driven programming

The 'post' section acts like event handlers triggered by pipeline completion events.

Understanding event-driven patterns helps grasp how Jenkins triggers post actions based on pipeline outcomes.

Transaction commit/rollback in databases

Like committing or rolling back a transaction after operations, 'post' runs steps based on success or failure.

This connection clarifies how pipelines finalize work conditionally, ensuring consistency.

Theatre play curtain call

The 'post' section is like the curtain call after a play, where actors come out regardless of the performance quality.

This cross-domain link shows how final steps always run to close the process, no matter what happened.

Common Pitfalls

#1 Assuming 'post' steps run immediately after each stage.

Wrong approach:

pipeline {
stages {
stage('Build') {
steps {
echo 'Building'
}
post {
success {
echo 'Build success'
}
}
}
}
post {
always {
echo 'Cleanup workspace'
}
}
}

Correct approach:

pipeline {
stages {
stage('Build') {
steps {
echo 'Building'
}
post {
success {
echo 'Build success'
}
}
}
}
post {
always {
echo 'Cleanup workspace'
}
}
}

Root cause:

Confusing stage-level 'post' with pipeline-level 'post' can lead to misunderstanding when steps run.

#2 Using 'failure' block to handle unstable results.

Wrong approach:

post {
failure {
echo 'Tests failed or unstable'
}
}

Correct approach:

post {
failure {
echo 'Hard failure occurred'
}
unstable {
echo 'Tests are unstable'
}
}

Root cause:

Not distinguishing between 'failure' and 'unstable' pipeline states causes incorrect handling.

#3 Not cleaning workspace in 'always' block, causing leftover files.

Wrong approach:

post {
success {
echo 'Success!'
}
}

Correct approach:

post {
always {
cleanWs()
}
}

Root cause:

Forgetting that cleanup must run regardless of success or failure leads to resource leaks.

Key Takeaways

The 'post' section in Jenkins pipelines runs steps after all stages finish, based on the pipeline result.

'success', 'failure', and 'always' are key conditions to handle different pipeline outcomes cleanly and reliably.

Using 'post' centralizes notifications, cleanup, and other follow-up tasks, improving pipeline maintainability.

You can define 'post' blocks at both pipeline and stage levels for flexible control.

Understanding the execution order and conditions of 'post' prevents common bugs and ensures consistent pipeline behavior.