Jenkins / Execution and source foundations / Lesson 1

Controller, agent, executor, and build identity

Locate scheduling, orchestration, process execution, and retained evidence before reading a Pipeline.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Distinguish controller, node, agent, executor, workspace, job, and run.
Explain why queueing does not imply an application failure.

Separate orchestration from build processes

Jenkins coordinates automation through a controller and execution nodes. Agents connect execution capacity to the controller; executors represent concurrent work slots on nodes. A workspace is a directory allocated for a job’s file operations, not a permanent release repository. The job defines a repeatable automation configuration, while each run records one invocation and its evidence. In the synthetic Parcel project, parcel-check is a job and its run number distinguishes attempts. A run number alone does not identify source bytes, dependency inputs, or a release candidate.

A queued run has not yet tested the application

A run can wait because no eligible executor is free, a label matches no connected node, a concurrency rule blocks it, or an upstream decision remains unresolved. Repeating the run adds more demand without proving the cause. Separate time waiting for capacity from time executing commands. The following diagram is a conceptual flow, not a running Jenkins installation. An allocated executor does not guarantee that the required interpreter, filesystem permission, network path, or application fixture exists on the selected node.

text A Jenkins execution boundary map

job request -> scheduling queue -> eligible executor
eligible executor -> workspace and steps -> retained run evidence

The arrows describe responsibilities rather than measured timings. No controller, agent, queue, filesystem workspace, or job is created or inspected by this example.

Friendly names are not immutable evidence

Labels help route work, job names help people navigate, and build numbers identify invocations within a job. None universally replaces an immutable source revision or package digest. Parcel’s evidence record should connect job and run, source revision, effective toolchain, test results, and produced candidate. A renamed job or rebuilt package can keep a familiar name while changing meaning. Preserve these relationships when investigating a surprising green result instead of treating the latest successful run as automatic approval for every downstream consumer.

Model eligibility before changing resources

The complete local model below counts free slots on nodes carrying a required label. It is deliberately static: it does not model Jenkins queue priorities, cloud provisioning, exclusive node mode, authorization, or plugin constraints. Its useful distinction is between matching a label and having spare eligible capacity. An offline node contributes nothing. Real diagnostics must use the owner’s authorized observations and avoid changing executors or agent connections just to test a hypothesis. More slots can also create contention for memory, disk, or shared dependencies.

python A static synthetic eligibility calculation

nodes = [{"labels": {"linux", "lab"}, "online": True, "free": 1}, {"labels": {"windows"}, "online": True, "free": 2}, {"labels": {"linux"}, "online": False, "free": 3}]
free = sum(n["free"] for n in nodes if n["online"] and "linux" in n["labels"])
print(free)
print("eligible" if free else "waiting")

Expected output

1
eligible

The program reads only declared dictionaries. A result of one is a model result, not actual Jenkins capacity or a guarantee that a queued run will start.

Execution capacity also carries authority

A node can expose host credentials, network access, persistent files, and privileged sockets to the commands it runs. Treat agent selection as a trust decision as well as a capacity decision. Untrusted proposal builds should not inherit production authority because they share a label with a release node. Controller isolation and agent-to-controller protections matter independently of workspace cleanup. This course performs no administrative operations; it teaches which boundaries must be reviewed before a real Jenkins owner authorizes execution.

Common errors and fixes

A queued run is diagnosed as a failed unit test.

Why it happens: The application has not executed; scheduling evidence was ignored.
How to fix it: Identify the queue reason and eligible node capacity first.
Prevent it next time: Track queue duration separately from step execution.

A job name is used as the release identity.

Why it happens: A mutable navigation label was confused with source and artifact identity.
How to fix it: Record immutable revision and candidate relationships with the run.
Prevent it next time: Keep job, run, source, and package identifiers distinct.

Adding executors is assumed to be a harmless speed improvement.

Why it happens: Resource contention and node authority were not reviewed.
How to fix it: Assess workload, isolation, and capacity with the platform owner.
Prevent it next time: Review execution slots as an operational and trust boundary.

Check your understanding

1. Two runs share one job name. Must they use identical source and tools?

Show worked solution

No. Each invocation can resolve another revision, dependency set, toolchain, or parameter value. The run record must identify its effective inputs. A shared job configuration explains intended behavior but is not proof of equal build bytes.

2. A node has the required label but is offline. Does its configured executor count help the waiting job?