Jenkins Lesson 9 – Build Lifecycle | Dataplexa

Jenkins Course

I. Jenkins Fundamentals
1. What is Jenkins 2. Why Jenkins is Used 3. Jenkins Architecture 4. Master and Agent Model 5. Jenkins Installation Overview 6. Initial Setup and UI 7. Jenkins Jobs Overview 8. Freestyle Jobs 9. Build Lifecycle 10. Beginner Best Practices
II. Jenkins Pipelines
11. What is Jenkins Pipeline 12. Declarative vs Scripted 13. Jenkinsfile Introduction 14. Pipeline Syntax 15. Stages and Steps 16. Environment Variables 17. Job Parameters 18. Credentials Management 19. Pipeline Triggers 20. Pipeline Notifications 21. Pipeline with Git 22. Pipeline with Docker 23. Pipeline with Kubernetes 24. Handling Pipeline Failures 25. Pipeline Best Practices
III. Security, Plugins & Scaling
26. Plugins Overview 27. Plugin Management 28. Jenkins Security Model 29. Users, Roles and Permissions 30. Securing Credentials 31. Backup and Restore 32. Logging and Monitoring 33. Performance Tuning 34. Distributed Builds 35. Scaling Jenkins
IV. Advanced Jenkins & Real-World
36. Jenkins as Code 37. Configuration as Code 38. Jenkins in Cloud Environments 39. Jenkins on Kubernetes 40. Jenkins and Infrastructure as Code 41. Jenkins for Microservices 42. Migration Strategies 43. Troubleshooting 44. Jenkins Anti-Patterns 45. Mini Project
Section I · Lesson 9

Build Lifecycle

A build doesn't just "run." It moves through a precise sequence of states — from the moment something triggers it to the moment Jenkins records the final result. Understanding that sequence is the difference between guessing why a build behaved oddly and knowing exactly where it went wrong.

This lesson covers

Trigger → Queue → Agent assignment → Workspace prep → Execution → Post-build → Result recording — every state a build passes through, and what can go wrong at each one

Here's a question most Jenkins users can't answer confidently: what is the difference between a build that is queued and one that is pending? What exactly happens between "trigger fires" and "first command runs"? Why does a build sometimes sit doing nothing for 30 seconds before any output appears?

All of those answers live in the build lifecycle. Once you have this mental model locked in, the Jenkins dashboard stops being a mystery and starts being a diagnostic tool.

The Analogy That Makes It Click

Think of a build like an Uber ride request. You tap the button (trigger). The request enters a pool waiting for a nearby driver (queue). A driver accepts and starts heading to you (agent assigned). They arrive and you get in (workspace prepared). The car drives you to your destination (build steps execute). You arrive, rate the trip, and the receipt is sent (post-build actions, result recorded). If no drivers are available, you just wait in the queue. If the car breaks down mid-trip, the ride ends in failure.

The Complete Build Lifecycle

Every build — Freestyle or Pipeline — passes through these seven states in order. No state is skipped, though some are very fast.

1

Trigger Fires

INSTANT

Something tells Jenkins to run the job. Could be a code push (via webhook or SCM poll), a schedule (cron), another job completing, or a human clicking Build Now. Jenkins receives the signal and immediately creates a build record with a number.

2

Waiting in Queue

SECONDS TO HOURS

The build waits for a free executor on a matching agent. If agents are busy, it just sits here. You can see queued builds in the Build Queue panel on the dashboard. The queue shows why the build is waiting — "Waiting for next available executor" or "All agents with label 'linux' are offline."

3

Agent Assigned

FAST

The master finds an available agent with the right label and claims one of its executors. The build is now "assigned" — no longer in the queue, not yet running. The master sends the job instructions to the agent over SSH or JNLP.

4

Workspace Prepared

SECONDS

Jenkins creates (or reuses) a workspace directory on the agent. Then it checks out the source code — cloning the repo or doing a git pull if the workspace already exists. This is the "Cloning repository..." step you see at the top of console output.

5

Build Steps Execute

THE MAIN EVENT

Your commands run — tests, compilation, Docker builds, deployments, whatever the job defines. Console output streams back to the master in real time. If any step fails and returns a non-zero exit code, Jenkins stops execution here and jumps straight to post-build.

6

Post-Build Actions Run

ALWAYS RUNS

Notifications get sent, test reports get published, artifacts get archived, downstream jobs get triggered. Critically — post-build actions run whether the build passed or failed. This is how Slack gets notified about broken builds.

7

Result Recorded

FINAL STATE

Jenkins writes the final result to disk — SUCCESS, FAILURE, UNSTABLE, or ABORTED. The build log is saved. The dashboard dot changes colour. The executor is freed up for the next build in the queue.

The Four Final States — and What Each Means

SUCCESS

Every build step completed and every command returned exit code 0. All is well. Dashboard dot turns green (or blue, depending on your theme plugin).

FAILURE

A build step returned a non-zero exit code, or a pipeline stage explicitly failed. Something broke. Dashboard dot turns red. Investigate the console output.

UNSTABLE

The build ran to completion but something wasn't quite right — usually test failures that were configured as warnings rather than errors. Dashboard dot turns yellow. Not great, not broken.

ABORTED

A human or a timeout stopped the build mid-run. Not a failure — the build was interrupted intentionally. Dashboard dot turns grey.

Inspecting a Build's Lifecycle From the Terminal

The scenario:

You're a platform engineer at a media company. A developer messages you: "the payment-service build has been stuck for 20 minutes — is it running or queued?" You need to check the build's current state and duration without leaving the terminal. This command gives you the full picture of the most recent build for any job.

Tools used:

  • Jenkins REST API — every job and build in Jenkins has its own API endpoint. Appending /api/json to a build URL returns that build's data as JSON — result, duration, timestamp, currently building flag, and more.
  • lastBuild — a special Jenkins API shortcut. Instead of knowing the build number, you can use lastBuild to always get the most recent one.
  • curl — makes the HTTP GET request to the Jenkins API.
  • python3 -m json.tool — formats the JSON response for readability.
# Fetch the current state of the most recent build for a specific job
# 'lastBuild' is a Jenkins shortcut — always points to the newest build number
# 'tree' limits the response to only the fields we care about
curl \
  --user admin:your-api-token \
  "http://jenkins-master-01:8080/job/payment-service-build/lastBuild/api/json?tree=number,result,duration,timestamp,building,builtOn" \
  | python3 -m json.tool

Where to practice: Point this at any job on your local Jenkins instance — replace payment-service-build with any job name from your dashboard. If you built the inventory-api-test job in Lesson 8, use that. Full build API reference at jenkins.io — Remote Access API.

{
  "_class": "hudson.model.FreeStyleBuild",
  "number": 14,
  "result": null,
  "duration": 0,
  "timestamp": 1710324180000,
  "building": true,
  "builtOn": "agent-linux-01"
}

What just happened?

  • "building": true — this is the key field. It tells you the build is actively running right now on an agent. If this were false, the build has finished.
  • "result": null — when a build is still running, Jenkins has no result yet, so it returns null. Only after the build finishes does this become "SUCCESS", "FAILURE", "UNSTABLE", or "ABORTED". A null result combined with building: true means it's running. A null result combined with building: false would mean something went very wrong.
  • "duration": 0 — duration is always 0 while a build is in progress. Jenkins only writes the final duration when the build completes.
  • "timestamp": 1710324180000 — this is when the build started, in Unix epoch milliseconds. To convert: divide by 1000 to get seconds, then use date -d @1710324180 on Linux to see a human-readable time. This tells you exactly how long ago the build started.
  • "builtOn": "agent-linux-01" — the build is running on agent-linux-01. Now you know which machine to SSH into if you need to investigate further — check disk space, running processes, or network connectivity from that agent.
  • Answer to the developer's question — the build is running (not queued), it's been running since timestamp 1710324180, and it's on agent-linux-01. You have everything you need to either wait or escalate.

Where Builds Go Wrong — State by State

Knowing the lifecycle means knowing where to look when something breaks. Each state has its own failure mode:

State Symptom First place to check
Queue Build never starts, sits waiting forever Check if agents with the required label are online
Agent Assign Build assigned but nothing happens Check agent connectivity and Java version on the agent
Workspace Prep Fails at "Cloning repository" step Check Git credentials stored in Jenkins and repo URL
Build Steps Build fails mid-run Read the console output — find the first non-zero exit code
Post-build Build shows SUCCESS but notifications don't fire Check the post-build plugin config and credentials (e.g. Slack token)

Teacher's Note

When a build misbehaves, the first question is always: which state is it stuck in? That question cuts debugging time in half.

Practice Questions

1. A build runs all the way to completion but some tests are configured as warnings rather than hard failures. What result state does Jenkins record?



2. What value does the Jenkins API return for a build's result field while the build is still running?



3. What Jenkins API shortcut always points to the most recent build of a job, without needing to know its build number?



Quiz

1. A build has been sitting in the queue for 10 minutes. What needs to happen for it to move to the next state?


2. A build step fails mid-run. What happens to the post-build actions?


3. A build fails at the workspace preparation stage with an error cloning the repository. What is the first thing to check?


Up Next · Lesson 10

Beginner Best Practices

The ten habits that separate a Jenkins setup that holds together from one that quietly falls apart under pressure.

← Previous Course Index Next →