Jenkins and CI/CD Foundations, Controller-Agent Architecture, Jobs, Builds, and Automation Boundaries: Concepts, Architecture, and Mental Model

1. The practical problem: “Jenkins ran it” is not an explanation

Jenkins is often introduced with a short recipe: install the server, create a job, click Build Now, and read the console. That is enough to produce a first green icon, but it is not enough to operate Jenkins safely. When a production build is delayed or wrong, engineers need to answer much more precise questions: Which item was configured? What caused this particular run? Did the request enter the queue? Which label expression was evaluated? Which node accepted the work? Which executor and workspace were used? Which source revision was built? Which files were archived? Did an external deployment actually become healthy?

Those questions belong to different layers. A build can be queued but never allocated. An agent can be online but have the wrong labels. A shell step can return zero while the expected report is never published. An artifact can be archived correctly while a later deployment points at a different image digest. Jenkins is useful precisely because it coordinates these layers, but that coordination is reliable only when you preserve the identities that connect them.

2. The controller-agent mental model

Start with intent. A user, schedule, webhook, SCM poll, API call, or upstream job causes Jenkins to consider an item for execution. The controller owns the item definition and the scheduling decision. If the work needs an executor, Jenkins creates a queue item and looks for a node whose labels, availability, executor capacity, and other constraints match. The selected agent provides the process environment and workspace in which build steps run.

flowchart TD
  A[User, SCM, timer, webhook, API, or upstream cause] --> B[Controller + item/job configuration]
  B --> C[Queue item]
  C --> D[Label / node eligibility]
  D --> E[Executor allocation on an agent]
  E --> F[Workspace + source + toolchain]
  F --> G[Pipeline or job steps]
  G --> H[Build result + logs + reports + artifacts]
  H --> I[External publication / deployment / notification]
  I --> J[Target health + retained operational evidence]

The diagram is deliberately vertical. Each arrow is a checkpoint. If a build is waiting, do not jump straight to the shell command. If the queue says no node matches linux && lab, the script has not started yet. If the console says an API returned HTTP 202, the external service may only have accepted a request. Diagnosis improves when you ask, “At which boundary did the expected state stop advancing?”

3. Core objects and the evidence they own

4. Controller state is not agent state, and workspace state is not evidence

The controller and agent are cooperating processes with different trust and persistence properties. The controller owns scheduling and long-lived Jenkins metadata. The agent is where build-controlled commands usually execute. A workspace is local execution state: it can be wiped, reused, deleted with an ephemeral agent, or changed by a later build. Therefore a file existing in $WORKSPACE is not the same as a file being archived, published, signed, or deployed.

This distinction also explains the current controller-isolation guidance. A build on the built-in node executes in the controller process environment and can reach the controller filesystem with the Jenkins process' privileges. That couples untrusted or merely buggy build logic to the most important state in the system. Modern operating practice sets built-in-node executors to zero after a separate agent path is available.

5. Build identity: names move, build records should not

A branch such as main is a moving reference. A Jenkins build number is stable only within its job. A useful evidence record therefore joins several identities: full job name, build number/URL, build cause, exact SCM SHA, Jenkinsfile/library revision when applicable, and execution node/workspace. If a release is produced, add the artifact digest and external repository identity.

pipeline {
  agent { label 'lab' }
  stages {
    stage('Observe identity') {
      steps {
        sh '''
          set -eu
          printf 'job=%s\n' "$JOB_NAME"
          printf 'build=%s\n' "$BUILD_NUMBER"
          printf 'build_url=%s\n' "$BUILD_URL"
          printf 'node=%s\n' "$NODE_NAME"
          printf 'workspace=%s\n' "$WORKSPACE"
        '''
      }
    }
  }
}

The environment variables above identify Jenkins-owned execution state. They do not, by themselves, prove which source commit was checked out. When the job uses SCM, record git rev-parse HEAD (or the equivalent SCM identifier) from the workspace and compare it with the expected revision.

6. A build cause explains why Jenkins scheduled the run

Jenkins records causes such as a user starting a build, a timer firing, an SCM poll detecting a change, an upstream build completing, or an API/remote trigger. The cause answers “why did this run exist?” It is separate from the source revision and separate from the eventual result.

In the UI, inspect the build overview and console header before rerunning. In later automation chapters you can query causes through supported Pipeline/API mechanisms, but Chapter 01 deliberately starts with read-only inspection so the learner sees the records Jenkins already preserves.

7. Jenkins automation, CI, continuous delivery, and deployment are related—not synonyms

8. Read-only inspection before changing anything

When you inherit a Jenkins environment, start by observing. On a disposable lab controller, the same habit prevents “fixes” from destroying useful evidence. Record the controller version and Java runtime, then inspect the item, its recent builds, queue, and node list. Do not start with a restart, plugin upgrade, workspace wipe, or rerun.

# Controller image version without creating persistent state
docker run --rm jenkins/jenkins:2.568.3-lts-jdk21 --version

# After the lab controller is running
docker logs --tail 80 jenkins-ch01-controller

docker exec jenkins-ch01-controller java -version

Inside a build, print only non-secret fields needed for evidence. Do not dump the full environment: Jenkins environment variables can contain credentials or security-relevant values in later chapters.

9. Security and performance begin with scheduling boundaries

Current Jenkins guidance advises moving normal builds off the built-in node. This is both a security and an availability decision: build scripts should not compete with the controller for the same filesystem and process privileges, and build CPU/heap pressure should not destabilize scheduling and the UI. It also makes the ownership boundary visible: controller problems and agent problems can be diagnosed independently.

Executor count is capacity, not a “make it faster” slider. Increasing executors on an agent can increase contention for CPU, memory, disk, network, Docker daemon capacity, or external rate limits. Chapter 01 therefore uses a single-executor disposable agent so queue and allocation behavior are easy to observe.

10. Common beginner misconceptions

11. Summary: model Jenkins as a chain of independently verifiable states

A Jenkins operating model becomes much easier to reason about once the controller, queue, agent, executor, workspace, build record, artifacts, and external systems are treated as separate layers. The evidence chain for a useful build is: controller/core/Java/plugin baseline → exact item → build cause/number → source revision → queue decision → node/label/executor/workspace → executed steps → reports/artifacts → external side effect → target health.

Lesson 2 turns this model into a disposable local lab and deliberately captures each identity before adding more Jenkins features.

Knowledge check

Official references and version notes

• Jenkins documentation — primary documentation hub.
• Jenkins Pipeline and Pipeline syntax — current Pipeline mental model and Declarative syntax.
• Java Support Policy — supported Java runtimes for Jenkins core, agents, and CLI components.
• Controller Isolation and Managing Nodes — controller/agent trust and executor guidance.
• Jenkins LTS changelog and Security advisories — current release/security state.
• Official Jenkins controller image and official inbound-agent image.