Agent Directive

Learn the concepts, parameters, execution environments, and scoping rules required to allocate infrastructure nodes and containers within a declarative pipeline.

What is the Agent Directive?

The agent directive is a mandatory structural element in a Declarative Jenkinsfile that dictates exactly where a pipeline, or a specific stage within it, will execute. It controls workspace allocation and instructs the central Jenkins controller on which worker node resources to provision for processing the pipeline steps.

Supported Agent Allocation Options

Jenkins evaluates the agent parameter utilizing distinct structural modes to target execution nodes:

• `agent any`: Instructs Jenkins to execute the pipeline or stage on any available and configured node across the cluster grid, regardless of its operating system type.
• `agent none`: Disables global asset allocations at the root pipeline container level. Enforces the rule that every single nested stage must explicitly declare its own local execution agent parameter.
• `agent { label 'mac-os-build' }`: Targets specific machines by forcing an exact match against configured label tags (e.g., restricting iOS app builds strictly to macOS agent systems).
• `agent { docker { image 'maven:3-alpine' } }`: Dynamically provisions an isolated Docker container context directly on a Docker-capable worker node, running all stage commands safely inside the container environment.

Key Concepts

Practical Jenkins Example

The following advanced blueprint demonstrates a multi-agent structure using `agent none` globally to distribute frontend and backend tasks to matching targeted environments:

pipeline {
    // 1. Disable global node binding to allow stage-level distribution
    agent none 


























    stages {
        stage('Compile Backend Assets') {
            // 2. Allocate an explicit Linux machine node matching a label
            agent { label 'ubuntu-worker-node' }
            steps {
                echo 'Executing Java compilation targets on an Ubuntu worker environment...'
                sh 'java -version'
            }
        }
        
        stage('Containerized Frontend Check') {
            // 3. Dynamically provision an isolated container for specific tools
            agent {
                docker {
                    image 'node:20-alpine'
                }
            }
            steps {
                echo 'Executing React testing suites inside an isolated Node container environment...'
                sh 'node --version'
                sh 'npm --version'
            }
        }
    }
}

Practice Exercise: Build a Distributed Agent Pipeline