Labels for agent selection in Jenkins - Commands & Configuration

Introduction

When you run Jenkins jobs, you want them to run on specific machines or environments. Labels help Jenkins pick the right machine (agent) to run your job based on what that machine can do.

When you have multiple Jenkins agents with different software installed and want jobs to run only where compatible tools exist

When you want to separate jobs by operating system, like running Windows jobs on Windows agents and Linux jobs on Linux agents

When you want to dedicate certain agents for heavy tasks and others for light tasks

When you want to control job distribution to avoid overloading a single agent

When you want to test your application on different environments automatically

Commands

This command starts a Jenkins agent and assigns it the labels 'linux' and 'java' so Jenkins knows this agent can run jobs requiring these labels.

Terminal

jenkins-agent --labels linux,java

Expected Output

INFO: Agent started with labels: linux, java

INFO: Connected to Jenkins master

→

--labels - Assigns labels to the agent for job selection

This command triggers the Jenkins job 'my-pipeline' and tells Jenkins to run it on an agent labeled 'linux'.

Terminal

jenkins-jobs --label linux build my-pipeline

Expected Output

Started build #42 on agent with label linux

Build queued

Build running

Build successful

→

--label - Specifies the label to select the agent for running the job

This command uses Jenkins CLI to start 'my-pipeline' and passes the parameter LABEL=java to select an agent labeled 'java'.

Terminal

jenkins-cli build my-pipeline -p LABEL=java

Expected Output

[Pipeline] Start of Pipeline

Running on agent with label java

[Pipeline] End of Pipeline

Finished: SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: Labels let Jenkins pick the right agent to run your job based on the agent's capabilities.

Common Mistakes

Not assigning any labels to agents and expecting jobs to run on them

Jenkins cannot match jobs to agents without labels, so jobs may stay queued or run on wrong agents

Always assign meaningful labels to agents that describe their environment or capabilities

Using labels in job configuration that do not match any agent labels

Jobs will not find a suitable agent and will remain queued indefinitely

Ensure job label selectors exactly match labels assigned to at least one agent

Summary

Assign labels to Jenkins agents to describe their environment or capabilities.

Use these labels in job configurations or commands to select the right agent for running jobs.

This ensures jobs run on compatible machines and resources are used efficiently.