Nodes and Labels
Nodes are the machines that run builds; labels tag them so pipelines can target the right environment.
agent { label 'linux && docker' }A node is any machine that can run builds — the controller itself or a connected agent. Labels are tags you attach to nodes so pipelines can request the right kind of machine.
Adding an agent
Under Manage Jenkins > Nodes > New Node, define the agent's name, remote workspace directory, number of executors, and its labels.
Using labels
Give agents descriptive labels like linux, windows, docker, or gpu. In a pipeline, agent { label 'linux' } runs only on a matching node.
Executors
Each node has a number of executors — the count of builds it can run simultaneously.
Example
pipeline {
agent none
stages {
stage('Linux build') {
agent { label 'linux' }
steps { sh 'uname -a' }
}
stage('Windows build') {
agent { label 'windows' }
steps { bat 'ver' }
}
}
}When to use it
- A 'windows' label is assigned to a Windows agent so .NET pipelines route exclusively to it using agent { label 'windows' }.
- A 'high-memory' label marks agents with 32 GB RAM so memory-intensive integration test jobs always land on them.
- An agent is taken offline gracefully with 'temporarily offline' status so no new builds start while the machine is being patched.
More examples
Add node and label via JCasC
Provisions a permanent SSH agent with multiple labels using Jenkins Configuration as Code YAML.
jenkins:
nodes:
- permanent:
name: build-agent-1
labelString: 'linux docker maven'
remoteFS: /home/jenkins/agent
launcher:
ssh:
host: 192.168.1.50
credentialsId: agent-ssh-key
sshHostKeyVerificationStrategy:
manuallyTrustedKeyVerificationStrategy:
requireInitialManualTrust: falseTarget a labeled agent in pipeline
Routes the pipeline to any agent tagged with both 'docker' and 'linux' labels using a boolean expression.
pipeline {
agent { label 'docker && linux' }
stages {
stage('Container Build') {
steps {
sh 'docker build -t myapp:${BUILD_NUMBER} .'
}
}
}
}Per-stage agent with different label
Assigns the build stage to a Maven agent and the security scan to a dedicated security-tools agent.
pipeline {
agent none
stages {
stage('Build') {
agent { label 'maven' }
steps { sh 'mvn package' }
}
stage('Security Scan') {
agent { label 'security-tools' }
steps { sh 'trivy image myapp:latest' }
}
}
}
Discussion