Jobs, Builds, Queues, and Workspaces
Scenario: Deleting a workspace is mistaken for deleting build history, revealing confusion between scratch space and durable records.
Four words that sound similar but mean very different things
Beginners almost universally mix up "job," "build," and "workspace" - which is understandable, since Jenkins itself uses them loosely in places. Getting them straight early saves a lot of confusion later, especially the very common mistake of thinking "delete the workspace" means "delete the history."
Analogy: Think of a restaurant kitchen. The job is the recipe card pinned to the wall - it doesn't change every night, it just describes how to make the dish (which ingredients, which steps, in what order). A build is one specific night's actual cooking of that recipe - dinner service #417, with its own timestamp, its own outcome (did the dish come out right?), and its own record in the kitchen's log book. The workspace is the literal counter space and cutting board used during that night's cooking - it gets wiped down and reused for the next dish. Wiping the counter (workspace) doesn't erase the log book entry for dinner #417 saying it went out cold and was sent back.
Getting this right matters because Jenkins keeps these as genuinely separate things with separate lifecycles, and mixing them up leads to real mistakes - like assuming a clean workspace means you've lost your build history, when you haven't.
Pipeline example
pipeline { agent any; stages { stage('Context') { steps { echo "${env.JOB_NAME} #${env.BUILD_NUMBER}" } } } }Four distinct Jenkins concepts
A job is durable configuration: the Pipeline definition, its triggers, parameters, permissions, and how long to keep records. A queue item is a request waiting for a free executor to become available - it hasn't started running yet. A build is one numbered execution of that job: it has a cause (who or what triggered it), inputs, a result, a log, and recorded actions. A workspace is mutable scratch disk space allocated on an agent for that build to actually run in - source code gets checked out there, compiled output lands there temporarily. Deleting a workspace removes files from disk, but it does not remove build history; deleting an old numbered build removes its recorded evidence, but it does not necessarily clean up every agent that ever hosted its workspace.
What this looks like in practice
$ ls /var/jenkins_home/jobs/my-app/builds/
417 418 419 lastFailedBuild -> 418 lastSuccessfulBuild -> 419
$ cat /var/jenkins_home/jobs/my-app/builds/419/build.xml | grep result
<result>SUCCESS</result>Notice: builds 417, 418, 419 are separate numbered records that persist even after their workspaces have been reused or wiped on the agent machine. lastFailedBuild and lastSuccessfulBuild are just pointers into that history - they exist independently of whatever is currently sitting in an agent's /workspace directory.
Reuse and isolation matter
Workspace paths can be reused across builds, and concurrent runs of the same job may get suffixed directories (like my-app@2) so they don't collide. Never treat a workspace path as if it were the permanent identity of an artifact, and never assume a previous checkout's files are still correct - another build may have already overwritten them. Cleaning a workspace before each build improves reproducibility (you know exactly what's there) at the cost of re-downloading dependencies every time. A common middle ground: keep dependency caches (like an npm or Maven cache) deliberately outside the deliverable output, and key that cache by tool version and lockfile hash so a cache hit is only reused when it's actually still valid. Use disableConcurrentBuilds whenever two simultaneous runs of the same job would fight over the same target - for example, two deployments to the same environment at once - or redesign the operation so it's safe to run twice in parallel.
A pitfall: "the workspace is gone, so we lost the build"
A team once needed to investigate build #417 from three weeks ago, found its workspace had already been overwritten by build #500's checkout, and panicked, assuming the evidence was gone forever. It wasn't - build #417's log, its recorded result, its archived artifacts (if any were archived), and its test reports all live independently of the workspace, in Jenkins' own build record storage. The workspace was only ever meant to be scratch space for the duration of one run. The actual lesson this incident teaches: if you need to keep something from a build long-term, explicitly archive it (with archiveArtifacts or junit) - don't rely on the workspace still being there later, because it usually won't be.
Reading scheduling evidence
When a run appears stuck, first determine whether it is queued (waiting for a machine) or executing (running, but slowly). Queue reasons will tell you why: a missing matching label, all matching nodes offline, no free executors, or an active concurrency lock. Once a build is actually allocated to a node, record which node, which workspace path, which revision, and what caused it - that's your starting point for any investigation. Separate "queue duration" from "stage duration" when diagnosing slowness: a growing queue with fast executions once they start suggests you need more capacity or better label matching; long stages on an otherwise idle agent point toward genuinely slow work or an external system being slow, not a scheduling problem at all. Retention policy needs to keep enough numbered builds, test trends, and logs to diagnose problems, while still bounding disk usage on the controller - workspace cleanup and build-history disposal are two separate knobs solving two separate problems, and a reliable job should be able to start from a completely empty workspace and still let you explain, months later, exactly which source revision and inputs produced build #417.
Goal: Practice the concrete behavior in jenkins-artifact-promotion. Learn sections have no Jenkins terminal; the Jenkins lab opens the real shared service in a new full-screen tab inside your private folder.