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.

Practice

1. What is the purpose of the post section in a Jenkins pipeline?

easy

A. To run steps after the main pipeline or stage finishes

B. To define environment variables for the pipeline

C. To specify the build agent for the pipeline

D. To declare input parameters for the pipeline

Solution

1. Step 1: Understand the role of the post section

   The post section is designed to run steps after the main pipeline or stage finishes, regardless of success or failure.

2. Step 2: Compare with other pipeline sections

   Other sections like environment, agent, and parameters serve different purposes, not for post-run steps.

3. Final Answer:

   To run steps after the main pipeline or stage finishes -> Option A

4. Quick Check:

   Post section = run after pipeline [OK]

Hint: Post section always runs after pipeline ends [OK]

Common Mistakes:

• Confusing post with environment or agent sections
• Thinking post runs before pipeline starts
• Assuming post only runs on failure

2. Which of the following is the correct syntax to run a step only when the pipeline succeeds in the post section?

easy

A. post { always { echo 'Done' } }

B. post { success { echo 'Build succeeded' } }

C. post { failure { echo 'Build failed' } }

D. post { cleanup { echo 'Cleaning up' } }

Solution

1. Step 1: Identify the correct post condition for success

   The success block runs only when the pipeline finishes successfully.

2. Step 2: Check syntax correctness

   post { success { ... } } is the correct syntax. Other options use wrong conditions or invalid keywords.

3. Final Answer:

   post { success { echo 'Build succeeded' } } -> Option B

4. Quick Check:

   Success block runs on success [OK]

Hint: Use 'success' block for success-only steps [OK]

Common Mistakes:

• Using 'always' instead of 'success' for success-only steps
• Using invalid keywords like 'cleanup'
• Confusing 'failure' with 'success'

3. Given this Jenkins pipeline snippet, what will be printed if the build fails?

pipeline {
  agent any
  stages {
    stage('Test') {
      steps {
        sh 'exit 1'
      }
    }
  }
  post {
    success {
      echo 'Build succeeded'
    }
    failure {
      echo 'Build failed'
    }
    always {
      echo 'Build finished'
    }
  }
}

medium

A. Build failed
Build finished

B. Build succeeded

C. Build succeeded
Build finished

D. Build finished

Solution

1. Step 1: Analyze the build result

   The shell command sh 'exit 1' causes the build to fail.

2. Step 2: Determine which post blocks run on failure

   The failure block runs on failure, printing 'Build failed'. The always block runs regardless, printing 'Build finished'. The success block does not run.

3. Final Answer:

   Build failed Build finished -> Option A

4. Quick Check:

   Failure + always blocks run on failure [OK]

Hint: Failure and always blocks run on failure [OK]

Common Mistakes:

• Assuming success block runs on failure
• Ignoring the always block
• Thinking only failure block runs

4. Identify the error in this Jenkins pipeline post section:

post {
  success {
    echo 'Success!'
  }
  failure {
    echo 'Failure!'
  }
  always {
    echo 'Always runs'
  }
  cleanup {
    echo 'Cleaning up'
  }
}

medium

A. The 'always' block should be named 'alwaysRun'

B. The 'failure' block must come before 'success'

C. The 'cleanup' block is invalid in the post section

D. The 'echo' commands must be inside 'steps' block

Solution

1. Step 1: Review valid post condition blocks

   Valid blocks are success, failure, always, unstable, and changed. There is no cleanup block.

2. Step 2: Check syntax of echo commands

   The echo commands can be used directly in post blocks. The order of blocks does not matter.

3. Final Answer:

   The 'cleanup' block is invalid in the post section -> Option C

4. Quick Check:

   Only success, failure, always allowed [OK]

Hint: Post section allows only specific blocks like success, failure, always [OK]

Common Mistakes:

• Adding unsupported blocks like 'cleanup'
• Thinking block order matters
• Wrapping echo in steps inside post (not needed)

5. You want to send a notification only if the build fails, but also always archive the build logs regardless of the result. Which post section correctly implements this?

hard

A. post { failure { mail to: '[e-mail]' archiveArtifacts 'logs/**' } }

B. post { always { mail to: '[e-mail]' } failure { archiveArtifacts 'logs/**' } }

C. post { success { mail to: '[e-mail]' } always { archiveArtifacts 'logs/**' } }

D. post { failure { mail to: '[e-mail]' } always { archiveArtifacts 'logs/**' } }

Solution

1. Step 1: Identify notification condition

   Notification should run only on failure, so it belongs in the failure block.

2. Step 2: Identify archiving condition

   Archiving logs should happen always, so it belongs in the always block.

3. Step 3: Check syntax correctness

   post { failure { mail to: '[e-mail]' } always { archiveArtifacts 'logs/**' } } correctly separates the two actions into failure and always blocks. post { failure { mail to: '[e-mail]' archiveArtifacts 'logs/**' } } puts both actions in the failure block, so archiving occurs only on failure.

4. Final Answer:

   post { failure { mail to: '[e-mail]' } always { archiveArtifacts 'logs/**' } } -> Option D

5. Quick Check:

   Failure for notify, always for archive [OK]

Hint: Use failure for notify, always for archive [OK]

Common Mistakes:

• Putting always steps inside failure block
• Sending notifications on success instead of failure
• Missing proper syntax for multiple steps