A first, plain-language look at the idea before any details.

Jenkins is a free, open-source automation server. Teams use it to build software, test it, and deliver it to servers without doing every step by hand. The work Jenkins performs is described in a pipeline, which is simply a recipe written as a text file, usually named the Jenkinsfile. A pipeline is split into stages, such as Build, Test and Deploy, and each stage contains steps, which are the individual actions, like running a command or copying a file.

The post section is a part of that recipe that runs when a stage or the whole pipeline is finished. Its job is to react to the outcome. It can say “always do this,” “only do this when something broke,” or “only do this when things got better than last time.” You write these reactions once, and Jenkins applies them on every run automatically.

The three questions it answers

Every closing checklist answers three simple questions. First, what must always happen, such as saving test results and deleting temporary files. Second, what must happen only on a certain outcome, such as alerting the team when the build breaks. Third, what must happen only when the outcome changed, such as announcing that a broken build is finally repaired. The post section has a named slot for each of these questions.

A real-world picture helps. Large engineering organizations such as Netflix and Etsy have publicly described using Jenkins to build and test huge amounts of code every day. At that volume, nobody can watch each build. The end-of-build reactions must be written down in advance, and the post section is where they live.

The problem it solves, and the short history behind it.

The problem: builds end in many different ways

A naive pipeline is written as a straight line: do step one, then step two, then step three. That works only when everything succeeds. In real life, step two fails, and the line stops. Anything you placed after the failing step never runs. If your “delete temporary files” action was the last step, it is skipped exactly when the machine is in the messiest state.

This creates three classic pains. Test reports are lost because the command that ran the tests failed before the report-saving step. Disk space disappears because leftover files from failed builds pile up on the machine. Failures go unnoticed because the notification step was also at the end of the line and never executed.

A short history

Five small ideas that make everything else easy.

Agent

An agent is the machine (or container) where the steps actually run. Jenkins has a main brain called the controller, which schedules work, and worker machines called agents that do the heavy lifting. Think of the controller as a kitchen manager and the agents as the cooks.

Workspace

A workspace is a folder on the agent where the pipeline downloads code, compiles it and writes output. It is the cook’s workbench. Many post actions, such as collecting test reports, need this workbench to still exist, which is why the location of your post block matters.

Build status

Every run finishes with a result. Jenkins uses a small fixed vocabulary for it, and the post conditions are built on top of this vocabulary.

Previous build

Jenkins remembers every past run of a job. Some post conditions compare today’s result with the last completed run. That memory is what allows Jenkins to say “this is newly broken” or “this is newly fixed.”

Steps and plugins

A step is a single action. Many steps come built in, and many more come from plugins, which are add-on packages that teach Jenkins new tricks, such as sending chat messages or publishing test graphs. Your post section will mostly call these steps.

Which parts of a Jenkins setup are involved when a post section runs.

The post section is not a separate machine or service. It is part of the same pipeline run, executed by the same engine. Still, it touches many components, and understanding them explains almost every surprising behavior you will meet later.

flowchart LR
    DEV["Developer pushes code"] --> SCM["Source Control Server"]
    SCM -->|"webhook"| CTRL["Jenkins Controller"]
    CTRL -->|"assigns work"| AGT["Build Agent"]
    AGT --> WS["Workspace Folder"]
    AGT -->|"stage steps"| STG["Stages: Build, Test, Deploy"]
    STG -->|"result known"| POST["Post Section"]
    POST -->|"save files"| ART["Artifact Storage"]
    POST -->|"publish results"| REP["Test Report Views"]
    POST -->|"send messages"| NOTI["Chat and Email Services"]
    POST -->|"tidy up"| WS
    CTRL --> HIST["Build History Records"]
    POST -->|"final status"| HIST

Read the diagram from left to right. A developer pushes code to a source control server such as GitHub or GitLab. A webhook, which is an automatic message sent when something happens, tells the Jenkins controller about it. The controller hands the job to an agent. The agent creates a workspace and runs the stages. When the stages finish, the post section reacts. It saves files to artifact storage, publishes test results to report views, sends messages through chat and email services, tidies the workspace, and finally lets the final status land in the build history.

Two possible homes, one simple shape.

The shape of a post section is easy to describe in words. It is a block named post. Inside it you place one or more condition blocks, each named after a condition such as always or failure. Inside each condition block you place ordinary steps. You need at least one condition block, and you may use as many as you like.

Home one: the pipeline level

When the post block sits at the top level, next to the list of stages, it runs once, after every stage has finished. It sees the final result of the entire run. This is the right home for anything about the run as a whole: the final notification, the final workspace cleanup, the final summary.

Home two: the stage level

When the post block sits inside a stage, it runs right after that stage’s own steps finish, before the next stage begins. It sees only that stage’s result. This is the right home for anything tied to that stage: saving that stage’s test report, stopping a test database started only for that stage, or collecting that stage’s logs.

How to read a post block quickly

Each condition is a question Jenkins asks about the finished run.

Here is every condition, explained with the question it answers and a natural use. Read them once, then use the table in Chapter 9 to see how three of them compare runs over time.

Choosing between similar conditions

Beginners often ask why there are so many. The answer is that each removes noise. If you only had always, you would need to write “if failed then…” inside it, repeated everywhere. Named conditions let Jenkins do that checking for you and keep the recipe readable.

What Jenkins actually does, in order, when a run ends.

Understanding order removes most confusion. There are two layers of order: the order between stage-level and pipeline-level post blocks, and the order among the conditions inside one block.

flowchart TD
    S1["Stage 1: Build steps"] --> P1["Stage 1 post block"]
    P1 --> S2["Stage 2: Test steps"]
    S2 --> P2["Stage 2 post block"]
    P2 --> S3["Stage 3: Deploy steps"]
    S3 --> P3["Stage 3 post block"]
    P3 --> PP["Pipeline level post block"]
    PP --> END["Final result recorded"]

Layer one: stage before pipeline

A stage’s post block runs immediately after that stage’s steps finish. If the stage failed, the pipeline normally stops moving forward to later stages, but the failed stage’s own post block still runs. After all the stages that were going to run have run, the pipeline-level post block runs once.

Layer two: the order among conditions

Inside a single post block, Jenkins first works out the result, then checks each condition in a fixed order. Every condition that matches gets its steps executed. Several can match at once. For example, a failing run after a successful run matches changed, regression, failure and unsuccessful, along with always and cleanup.

flowchart TD
    A["Run finishes and result is known"] --> B["always"]
    B --> C["changed"]
    C --> D["fixed"]
    D --> E["regression"]
    E --> F["aborted"]
    F --> G["failure"]
    G --> H["success"]
    H --> I["unstable"]
    I --> J["unsuccessful"]
    J --> K["cleanup"]
    K --> L["Post block complete"]

Each box in Figure 3 only runs its steps if its own question is answered “yes” for this run. The order never changes, no matter how you arrange the blocks in the file. The important promise is that cleanup is last, so anything that deletes files will not remove them before the earlier conditions have finished using them.

What if a stage is skipped?

Stages can be skipped by a when rule, which says “only run this stage if a condition is true.” A skipped stage is treated as not built, and its own post block does not run, because there was no stage execution to react to. The pipeline-level post block still runs as normal.

Where the result comes from, and how post steps can change it.

Jenkins tracks a result for the run as it goes. When a step fails, the result becomes failure and later stages are skipped by default. When the tests step reports failing tests but keeps going, the result becomes unstable. When a person presses stop, the result becomes aborted.

Two names that sound alike

Pipeline files can read the build through a built-in object called currentBuild. It has a property named result and another named currentResult. The first can be empty while a run is still healthy and in progress, because Jenkins only fills it in when something changes it. The second always has a value and is the better one to read inside a post block when you want to describe the run in a message.

Post steps can make things worse

Post steps are real steps. If one of them fails, for example an email server cannot be reached and the mail step raises an error, that failure can turn an otherwise successful run into a failed one. This surprises many teams. A sensible design treats notification steps as helpful, not vital, and protects them so that a broken chat service does not make good code look bad.

Common ways a run becomes unstable

• A test reporting step finds failed tests but the test command itself was allowed to continue.
• A code-quality tool reports more violations than the agreed limit.
• A step was told, on purpose, to mark the build yellow instead of red when it hits a known soft problem.

Knowing this, you can decide which outcomes deserve a loud alert and which deserve a quiet note.

Three conditions that give Jenkins a memory.

Most conditions look only at the current run. These three also look at the run before it. That memory is what makes messages helpful instead of repetitive. Imagine a build that fails for five hours. Without memory, the team gets an alert on every run and starts ignoring them. With memory, the team gets one alert when things broke and one when they were fixed.

Reading the table

The middle rows are the most instructive. A run that fails after another failure does not trigger changed, so the team is not spammed. A run that goes from failure to unstable does trigger changed, because the status is different, but it is neither a fix nor a regression: it is an improvement that is not yet complete.

Follow the files, reports and messages from workbench to the outside world.

During a run, the workspace fills up with source code, compiled output, test result files, logs and temporary data. The post section is the moment when the valuable pieces are rescued and the rest is discarded. Think of it as sorting the workbench at the end of the day: keep the finished product, file the paperwork, sweep the sawdust.

flowchart LR
    W["Workspace after stages"] --> R1{"Which files matter?"}
    R1 -->|"test result files"| T["Publish test report"]
    R1 -->|"packages and logs"| A["Archive artifacts"]
    R1 -->|"temporary data"| D["Discard"]
    T --> N["Notify people"]
    A --> N
    N --> C["Cleanup workspace"]
    D --> C
    C --> H["Result stored in history"]

This ordering is not accidental. Rescue comes before tidy because deleted files cannot be rescued. Notify comes before tidy because a message often links to files that must still exist. The fixed order of conditions in Chapter 7 exists to support exactly this lifecycle.

The everyday toolbox used in real post sections.

A useful mental model is that every post step belongs to one of four families: rescue (archive, publish), tell (mail, chat), tidy (clean, stop) and chain (trigger). If a step does not fit any family, it probably belongs in a regular stage rather than the post section.

The details that decide whether your post steps can actually reach their files.

The “no agent at the top” trap

Some pipelines declare that no agent is used at the top and give each stage its own agent instead. This saves machines, because a stage only holds a worker while it is really working. The trap is that a pipeline-level post block then has no workspace at all. Steps that need files, like archiving or cleaning, fail with an error saying the required context is missing. The fix is to run those steps inside a small block that requests an agent, or to move the file-based steps into stage-level post blocks where the agent still exists.

Containers as agents

Many teams run stages inside containers, which are lightweight, throw-away environments. A stage-level post block runs while that stage’s container is still alive, so it can read files written inside it. Once the stage ends, the container is removed. If you need something from inside the container, rescue it in that stage’s post block, not later.

Parallel stages

Jenkins can run several stages at the same time, called parallel branches. Each branch may have its own post block. This is useful when, for example, unit tests and browser tests run side by side and each publishes its own report. The pipeline-level post block still runs once after all branches are done.

Because it runs on every outcome, it deserves careful handling.

The post section touches secrets, files and external services, which makes it a sensitive place. It also runs when things have gone wrong, which is exactly when careless logging tends to leak information.

How to know that your closing checklist itself is healthy.

Logging

Post steps write to the same console log as every other step, and Jenkins labels the post section clearly in the run page. Get into the habit of printing one short line per post action, such as “archived 14 files” or “sent failure alert to channel.” When a message never arrives, this one line tells you whether the step ran at all.

Metrics worth watching

Monitoring plugins, such as the one that exposes Jenkins numbers in a format the Prometheus monitoring system can read, help you chart these values over time. Build dashboards, which are wall-sized status screens, are common in teams that want failures to be visible without opening Jenkins.

Reliable ways of arranging post blocks that many teams reuse.

Habits that look fine on day one and hurt on day ninety.

A checklist you can apply to any Jenkinsfile today.

Mistakes people make when they are new

Expecting typed order to matter. The order of conditions in the file does not change the order in which they run. Do not rely on writing one block above another.

Forgetting that stages can be skipped. A stage-level post block does not fire for a stage that never ran. If the message must be sent anyway, put it at the pipeline level.

Confusing unstable and failure. A yellow run is not a red run. If your alert only listens to failure, failing tests that mark the run unstable will slip past silently.

Ignoring aborted runs. When a person stops a run, helper services may still be running. An aborted or cleanup block is the safe place to shut them down.

Using conditions on a new job. The comparing conditions need history. On the very first run they cannot say much.

An honest look at what the post section does well and where it strains.

Trade-offs to weigh

There is no universally right answer. The correct trade-off depends on how large your team is, how expensive agents are, and how fast your builds must be. What matters is that you choose on purpose and write the reasoning down for the next person.

How the ideas look in the kinds of organizations that run Jenkins at scale.

flowchart TD
    RUN["Pipeline run ends"] --> Q1{"Result?"}
    Q1 -->|"Success"| OK["success block: tag and trigger deploy job"]
    Q1 -->|"Unstable"| UN["unstable block: soft warning to team"]
    Q1 -->|"Failure"| FA["failure block: alert and collect debug files"]
    Q1 -->|"Aborted"| AB["aborted block: stop helper services"]
    OK --> CL["cleanup block: delete workspace"]
    UN --> CL
    FA --> CL
    AB --> CL

Where the post section fits among older and alternative tools.

The scripted “finally” idea is the closest relative of the cleanup and always conditions. Both promise to run no matter what. The declarative version simply makes the promise easier to read and standard across teams. Teams that need exotic logic sometimes mix both styles, keeping the declarative structure and using a small scripted section inside a step when they need real programming control.

Follow one imaginary pipeline from the first push to the last cleanup.

Ideas stick better inside a story, so here is one. A small team owns an online booking service. Their Jenkinsfile has three stages: Build, Test and Package. Each of the Test and Package stages has its own post block, and the pipeline has one final post block with four conditions: always, regression, fixed and cleanup. The previous run on this branch was successful.

Notice how little the team had to do by hand. There was no need to remember to save reports, stop the database or send messages. The closing checklist handled it, in the right order, for both the bad run and the good one.

Symptoms, likely causes and calm fixes.

A calm debugging routine

1. Open the run page and find the post section in the console output. Confirm it started at all.
2. Check the result shown at the top. Was it red, yellow or gray? Match it with the condition you expected.
3. Read the previous run’s result if the condition compares runs.
4. Look at the agent and workspace messages for missing context or missing files.
5. Reproduce on a test branch by forcing the same result, then adjust one thing at a time.

Neighbors of the post section that people often mix it up with.

Three other features live close to the post section, and beginners often confuse them. Knowing the difference helps you choose the right tool.

A simple way to remember the difference: the other three tools shape how the run behaves while it is going, and the post section shapes what happens once it is over. A well-designed pipeline usually uses both. For example, a quality scan wrapped so it only marks the run yellow, and a post block that sends a gentle note on unstable and a firm alert on failure.

What happens to the post section when hundreds of builds run every day.

A single post section that takes ten seconds feels harmless. Multiply it by 500 builds a day and you spend well over an hour of agent time on wrap-up alone. Multiply it again by several agents waiting for cleanup to finish before they can take new work, and slow endings quietly become a queue for everyone. Scale changes the questions you ask about a post section: not only “does it work,” but “how long does it take, and who waits for it?”

Where the time goes

Scaling practices

• Set time limits on post steps that talk to the network, so one slow service cannot hold hundreds of agents.
• Prefer fresh, short-lived agents such as containers, which disappear after the run and reduce the need to delete files at all.
• Keep the post section small. If a task takes more than a minute, ask whether it belongs in a stage or a separate job.
• Limit stored history. Old runs and archived files use disk on the controller. Configure a policy to discard old builds and old artifacts, so the memory that powers changed and fixed stays quick to search.
• Share standard endings through a shared library so one improvement helps every pipeline.

Those numbers are only an illustration, but the lesson is real: shaving five seconds from a post section used at scale gives back more than forty minutes of agent time every day.

A gentle path for teams that still use freestyle jobs or scripted endings.

Many teams inherit jobs built years ago with web forms. Moving them to a declarative pipeline with a post section is easier when done in small, safe steps.

Coming from scripted try and finally

Teams with scripted pipelines can map ideas one to one. The code that always ran in the final section becomes the always or cleanup condition. The code inside a failure handler becomes failure. The comparison with the previous build, which scripted pipelines needed hand-written code for, is now free through changed, fixed and regression. The result is usually a shorter, easier-to-read file.

Every important word in this guide, in one place.

Short answers to the questions that come up most often.

The whole story in a few lines.

The post section is the closing checklist of a Jenkins pipeline. It exists because builds end in many different ways and the important wrap-up work must happen every time. You place it inside a stage for stage-owned work or beside the stages for whole-run work. You fill it with condition blocks that match the result and the history, and you fill those with small, safe steps. Used well, it saves evidence, keeps agents tidy, and makes alerts meaningful instead of noisy.