Labels for agent selection in Jenkins - Step-by-Step Execution

Process Flow - Labels for agent selection

Start Jenkins Job

↓

Check Job's Agent Label

↓

Find Agent with Matching Label

↓

Assign Job to Agent

↓

Run Job on Agent

↓

Job Complete

Jenkins uses labels to find an agent that matches the job's requested label, then runs the job on that agent.

Execution Sample

Jenkins

pipeline {
  agent { label 'linux' }
  stages {
    stage('Build') {
      steps { echo 'Building on Linux agent' }
    }
  }
}

This Jenkins pipeline runs the build stage on an agent labeled 'linux'.

Process Table

Step	Action	Label Checked	Agent Found	Job Assigned	Output
1	Start job	linux	No	No	Waiting for agent
2	Search agents	linux	Agent1 (linux)	No	Found agent with label 'linux'
3	Assign job	linux	Agent1 (linux)	Yes	Job assigned to Agent1
4	Run job	linux	Agent1 (linux)	Yes	Output: Building on Linux agent
5	Job complete	linux	Agent1 (linux)	Yes	Job finished successfully

💡 Job completes after running on agent with matching label 'linux'

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
Agent Selected	None	Agent1 (linux)	Agent1 (linux)	Agent1 (linux)	Agent1 (linux)
Job Status	Waiting	Waiting	Assigned	Running	Completed

Key Moments - 3 Insights

Why does the job wait at the start before running?

The job waits because Jenkins is searching for an available agent with the matching label, as shown in step 1 and 2 of the execution table.

What happens if no agent has the requested label?

The job will stay in the waiting state and not run, because Jenkins cannot assign it to any agent without the matching label, as seen in step 1 where no agent is found.

Can a job run on an agent without the requested label?

No, Jenkins strictly assigns the job only to agents that have the requested label, ensuring the job runs in the correct environment, as shown in step 3.

Visual Quiz - 3 Questions

Look at the execution table, at which step is the job assigned to an agent?

A Step 2

B Step 4

C Step 3

D Step 1

💡 Hint

Check the 'Job Assigned' column in the execution table.

According to the variable tracker, what is the job status after step 4?

A Waiting

B Running

C Assigned

D Completed

💡 Hint

Look at the 'Job Status' row after step 4 in the variable tracker.

If no agent has the label 'linux', what would happen to the job status?

A It would stay waiting indefinitely

B It would run on any available agent

C It would fail immediately

D It would run on the master node

💡 Hint

Refer to the key moment about what happens if no agent has the requested label.

Concept Snapshot

Jenkins uses labels to select agents for jobs.
Specify label in pipeline with agent { label 'name' }.
Jenkins finds an agent with that label.
Job runs only on matching labeled agent.
If no agent matches, job waits.
Labels ensure correct environment for jobs.

Full Transcript

This visual execution shows how Jenkins uses labels to select agents for running jobs. The job starts and Jenkins checks the requested label 'linux'. It searches for an agent with that label and finds Agent1. The job is assigned to Agent1 and runs there, producing the output 'Building on Linux agent'. The job completes successfully. Variables like 'Agent Selected' and 'Job Status' change step-by-step, showing the job moving from waiting to running to completed. Key moments explain why the job waits if no agent matches and why it cannot run on agents without the label. The quiz tests understanding of when the job is assigned, job status changes, and what happens if no matching agent exists.

Practice

1.

What is the main purpose of using labels in Jenkins agent selection?

easy

A. To store job build logs

B. To change the Jenkins user interface theme

C. To tell Jenkins which agent can run a specific job

D. To configure Jenkins system settings

Solution

1. Step 1: Understand Jenkins agent labels

   Labels are tags assigned to agents to identify their capabilities or roles.

2. Step 2: Purpose of labels in job assignment

   Jenkins uses these labels to select the right agent that matches the job requirements.

3. Final Answer:

   To tell Jenkins which agent can run a specific job -> Option C

4. Quick Check:

   Labels guide agent selection = A [OK]

Hint: Labels connect jobs to suitable agents quickly [OK]

Common Mistakes:

• Thinking labels change UI or store logs
• Confusing labels with system settings

2.

Which of the following is the correct syntax to select an agent with label linux and docker in Jenkins pipeline?

easy

A. agent { label linux docker }

B. agent { label 'linux, docker' }

C. agent { label 'linux || docker' }

D. agent { label 'linux && docker' }

Solution

1. Step 1: Understand label expressions in Jenkins

   Jenkins uses logical operators like && for AND and || for OR in label expressions.

2. Step 2: Correct syntax for AND condition

   To require both labels, use 'linux && docker' inside the label field.

3. Final Answer:

   agent { label 'linux && docker' } -> Option D

4. Quick Check:

   AND labels use && = D [OK]

Hint: Use && for AND, || for OR in label expressions [OK]

Common Mistakes:

• Using space-separated labels without operators
• Using commas instead of logical operators
• Confusing AND (&&) with OR (||)

3.

Given this Jenkins pipeline snippet, what agent will run the job if agents have labels linux, docker, and gpu?

agent { label 'linux && (docker || gpu)' }

medium

A. An agent with linux and either docker or gpu labels

B. An agent with linux and gpu labels

C. An agent with both linux and docker labels

D. Any agent with linux, docker, and gpu labels all together

Solution

1. Step 1: Analyze label expression

   The expression requires the agent to have the 'linux' label AND either 'docker' OR 'gpu' label.

2. Step 2: Determine matching agents

   Agents with 'linux' plus 'docker' or 'linux' plus 'gpu' satisfy the condition.

3. Final Answer:

   An agent with linux and either docker or gpu labels -> Option A

4. Quick Check:

   linux AND (docker OR gpu) = A [OK]

Hint: Parentheses group OR conditions, AND applies outside [OK]

Common Mistakes:

• Thinking all three labels are required
• Ignoring parentheses in label expressions
• Assuming OR means both labels must be present

4.

What is wrong with this Jenkins pipeline agent label expression that causes the job to wait indefinitely?

agent { label 'linux && docker || gpu' }

medium

A. Labels must be quoted with double quotes, not single quotes

B. Missing parentheses causing wrong operator precedence

C. Using commas instead of logical operators

D. Agent label cannot contain logical operators

Solution

1. Step 1: Understand operator precedence in label expressions

   Logical AND (&&) has higher precedence than OR (||), so expression is parsed as '(linux && docker) || gpu'.

2. Step 2: Identify why job waits

   If no agent has both linux and docker, but some have gpu alone, job may pick gpu agents. If gpu agents are missing or busy, job waits.

3. Final Answer:

   Missing parentheses causing wrong operator precedence -> Option B

4. Quick Check:

   Use parentheses to control label logic = C [OK]

Hint: Use parentheses to clarify label logic precedence [OK]

Common Mistakes:

• Ignoring operator precedence in label expressions
• Using wrong quote types
• Believing logical operators are not allowed

5.

You want a Jenkins job to run only on agents that have linux and docker labels but never on agents with gpu label. Which label expression should you use?

hard

A. linux && docker && !gpu

B. linux && docker || !gpu

C. linux && (docker || !gpu)

D. linux && docker && gpu

Solution

1. Step 1: Understand label requirements

   The job must run on agents with both 'linux' and 'docker' labels, but exclude any with 'gpu'.

2. Step 2: Construct correct label expression

   Use AND (&&) for required labels and NOT (!) to exclude 'gpu': 'linux && docker && !gpu'.

3. Final Answer:

   linux && docker && !gpu -> Option A

4. Quick Check:

   Include linux and docker, exclude gpu = B [OK]

Hint: Use ! to exclude labels in Jenkins expressions [OK]

Common Mistakes:

• Using OR instead of AND for required labels
• Not excluding gpu label properly
• Misplacing parentheses causing wrong logic