Controlling your build environment

In the quick start examples, you will have seen the agent directive in use. This specifies where and how Jenkins will run your build. This is required at the top level, and can also be used to override the top level agent settings for individual stages.

There are really 3 ways to use this (from quickest to most powerful):

1. With Docker

Use agent { docker 'node:6.0' to specify that you want Jenkins to pull the node:6.0 image from Docker Hub, and run the build inside it. This can pretty much be any image you like, your build steps and stages will run inside it. }

Example:

pipeline {
    agent {
        docker 'node'
    }
    stages {
        stage("testing 123") {
            steps {
                sh 'node --version'
            }
        }
    }
}

You can also use a Dockerfile in your source repository - with agent { dockerfile true }, the Dockerfile at the root of your repository will be built and the resulting image will be used for a container your build will run in.

Reusing node/workspace with per-stage Docker agents

Additionally, if you're running a Docker agent for a specific stage while specifying agent { label 'whatever' } at the top level, you can ensure that this stage will use the same node and workspace as the rest of the Pipeline:

pipeline {
  agent {
    label 'whatever'
  }
  stages {
    stage('build') {
      steps {
        sh "./build-artifact.sh"
      }
    }
    stage('test in docker') {
      agent {
        docker {
          image 'ubuntu:16.04'
          reuseNode true
        }
      }
      steps {
        sh "./run-tests-in-docker.sh"
      }
    }
  }
}

2. Specifying a Label for a Jenkins agent to run on

This is useful for when you want to specify a particular machine size, or requirement. Use agent { label 'windows' } to specify that you want your build to run on an agent that is labelled as windows. If you make this label '' then it will run on any agent connected to your Jenkins master that is available.

Example (will use the master node):

pipeline {
    agent {
        label 'master'
    }
    stages {
        stage('testing 123') {
            steps {
                sh 'echo hello from master node'
            }
        }
    }
}

3. I like to drive stick, get out of my way

In this case, put agent none as your agent directive. Pipeline won't try to find an agent to run on, or pull any Docker images. Inside your stage ... directives, you will need to specify what node to run on, should you need one.

Example:

pipeline {
    agent none
    stages {
        stage('say hi') {
            steps {
                echo "I don't need no node"
            }
        }
        stage('build') {
             agent {
                 label 'master'
             }
             steps {   
                checkout scm
                sh 'echo from master'
            }
        }
        stage('deploy') {
            agent {
                label 'deploy-host'
            }
            steps {
                sh './deploy-code-here'
            }
        }
    }
}

In this case, we have a few stages. The last 2 actually get different nodes to execute on (a node is a machine that is running the Jenkins agent). Note the checkout scm step - this actually fetches the code into the nodes workspace (previously it was done automatically for you).