agent Directive

agent Directive

The agent Directive and Its Options

agent decides where steps run: at the top for the whole pipeline, or in a stage for that stage only. agent any takes any free executor; agent { label 'linux && booknest' } takes a node matching a label expression (Agents, Nodes and Labels); agent { node { ... } } adds options such as customWorkspace; docker, dockerfile and kubernetes start a container per build (docker Agent Directives and Kubernetes Pod Templates). agent none allocates nothing, and each stage declares its own, which suits pipelines that wait:

decl-agent: agent none, a stage agent and a custom workspaceGroovy

pipeline {
  agent none
  stages {
    stage('Plan') {
      steps { echo "No node yet: NODE_NAME=${env.NODE_NAME}" }
    }
    stage('Build') {
      agent { label 'linux && booknest' }
      steps { sh 'echo "$NODE_NAME: $WORKSPACE"' }
    }
    stage('Shared workspace') {
      agent { node { label 'linux'; customWorkspace '/home/jenkins/agent/booknest-cache' } }
      steps { sh 'echo "$NODE_NAME: $WORKSPACE"' }
    }
  }
}

Output

No node yet: NODE_NAME=null
...
agent-1: /home/jenkins/agent/workspace/decl-agent
...
agent-1: /home/jenkins/agent/booknest-cache

Plan ran on no node: echo needs none, but a sh there failed a test job with "Attempted to execute a step that requires a node context while ‘agent none’ was specified." Each stage agent is a separate allocation, so pass files between stages with stash/unstash. A label no node carries never fails: label 'windows' waited with "There are no nodes with the label ‘windows’" until aborted.

MENU