How to Use Docker Agent in Jenkins Pipeline

In Jenkins pipeline, use agent { docker { image 'your-image' } } to run pipeline steps inside a Docker container. This lets you isolate your build environment by specifying the Docker image to use as the agent.

Syntax

The Docker agent syntax in a Jenkins pipeline defines the Docker container where your pipeline runs. It has these parts:

• agent: Declares where the pipeline or stage runs.
• docker: Specifies to use a Docker container as the agent.
• image: The Docker image name to run the container from.
• args (optional): Additional Docker run arguments like volume mounts or environment variables.

groovy

pipeline {
  agent {
    docker {
      image 'your-image:tag'
      args '-v /host/path:/container/path'
    }
  }
  stages {
    stage('Example') {
      steps {
        sh 'echo Hello from Docker agent'
      }
    }
  }
}

Example

This example runs a simple shell command inside an alpine Docker container. It shows how the pipeline uses the Docker agent to isolate the build environment.

groovy

pipeline {
  agent {
    docker {
      image 'alpine:3.18'
      args '-u root:root'
    }
  }
  stages {
    stage('Run Command') {
      steps {
        sh 'echo Hello from inside Alpine container'
        sh 'apk add --no-cache curl'
        sh 'curl --version'
      }
    }
  }
}

Output

[Pipeline] sh
+ echo Hello from inside Alpine container
Hello from inside Alpine container
[Pipeline] sh
+ apk add --no-cache curl
fetch http://dl-cdn.alpinelinux.org/alpine/v3.18/main/x86_64/APKINDEX.tar.gz
(1/1) Installing curl (8.2.1-r0)
Executing busybox-1.36.1-r7.trigger
OK: 6 MiB in 15 packages
[Pipeline] sh
+ curl --version
curl 8.2.1 (x86_64-alpine-linux-musl) libcurl/8.2.1 OpenSSL/3.1.1 zlib/1.2.13
Release-Date: 2023-04-05
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: AsynchDNS HTTPS-proxy IPv6 Largefile libz MultiSSL NTLM SPNEGO SSL TLS-SRP UnixSockets

Common Pitfalls

Common mistakes when using Docker agent in Jenkins pipelines include:

• Not having Docker installed or configured on the Jenkins agent machine.
• Using an image that lacks required tools or permissions.
• Forgetting to add necessary args like volume mounts for workspace persistence.
• Running commands that require root but not specifying user permissions.

Always verify your Docker image and Jenkins environment support the needed operations.

groovy

pipeline {
  agent {
    docker {
      image 'ubuntu:latest'
      // Missing args to mount workspace - leads to missing files
    }
  }
  stages {
    stage('Build') {
      steps {
        sh 'ls workspace'
      }
    }
  }
}

// Corrected version with args to mount workspace
pipeline {
  agent {
    docker {
      image 'ubuntu:latest'
      args '-v $WORKSPACE:$WORKSPACE -w $WORKSPACE'
    }
  }
  stages {
    stage('Build') {
      steps {
        sh 'ls workspace'
      }
    }
  }
}

Quick Reference

Use this quick reference to remember key Docker agent options in Jenkins pipelines:

Option	Description	Example
agent	Defines where pipeline runs	agent { docker { image 'alpine' } }
docker	Use Docker container as agent	docker { image 'node:18' }
image	Docker image name and tag	image 'python:3.11'
args	Extra Docker run options	args '-v /host:/container'
label	Specify Jenkins node label	agent { docker { image 'golang' label 'docker-node' } }

Key Takeaways

Use the Docker agent in Jenkins pipeline with agent { docker { image 'your-image' } } to run steps inside a container.

Add args to the docker agent to pass volume mounts or user permissions for workspace access.

Ensure Docker is installed and the image has required tools for your build.

Test your pipeline with simple commands inside the Docker container to verify setup.

Use the Quick Reference table to remember common Docker agent options.