How to Label Agent in Jenkins: Simple Guide

In Jenkins, you label an agent by setting a Label in the agent's configuration under Manage Jenkins > Manage Nodes. This label lets you target specific agents for running jobs by specifying the label in the job's Restrict where this project can be run option.

Syntax

To label an agent in Jenkins, you assign a label string to the agent configuration. This label is a simple word or phrase that identifies the agent.

Example syntax for using a label in a Jenkins pipeline:

agent { label 'my-agent-label' }

Here:

• agent defines where the pipeline runs.
• label 'my-agent-label' tells Jenkins to run the job on an agent with that label.

groovy

pipeline {
  agent { label 'my-agent-label' }
  stages {
    stage('Example') {
      steps {
        echo 'Running on labeled agent'
      }
    }
  }
}

Example

This example shows how to label an agent and use that label in a pipeline job.

First, assign the label linux-agent to your Jenkins node in Manage Jenkins > Manage Nodes. Then use this label in your pipeline script to run the job on that agent.

groovy

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

Output

[Pipeline] echo
Building on linux-agent
[Pipeline] End of Pipeline

Common Pitfalls

Common mistakes when labeling agents include:

• Not assigning the label to any agent, so the job cannot find a matching node.
• Typos in the label name in the job or agent configuration.
• Using multiple labels incorrectly without proper syntax.

Always verify the label exists on at least one agent and matches exactly.

groovy

/* Wrong: label not assigned to any agent */
pipeline {
  agent { label 'missing-label' }
  stages {
    stage('Test') {
      steps {
        echo 'This will fail if no agent has this label'
      }
    }
  }
}

/* Right: label matches an existing agent */
pipeline {
  agent { label 'existing-label' }
  stages {
    stage('Test') {
      steps {
        echo 'Runs successfully on labeled agent'
      }
    }
  }
}

Quick Reference

Concept	Description
Agent Label	A tag assigned to a Jenkins node to identify it.
Assign Label	Set label in node configuration under Manage Jenkins > Manage Nodes.
Use Label	Specify label in job configuration or pipeline with agent { label 'name' }.
Multiple Labels	Use space-separated labels to match any of them.
Label Matching	Job runs on any agent with at least one matching label.

Key Takeaways

Assign labels to Jenkins agents in Manage Nodes to identify them.

Use the label in pipeline scripts with agent { label 'your-label' } to run jobs on specific agents.

Labels must exactly match between agent and job to work correctly.

Check for typos and ensure at least one agent has the label before running jobs.

Multiple labels can be used but must be space-separated and correctly referenced.