How to Use docker.image in Jenkins Pipeline

In Jenkins Pipeline, use docker.image('image_name').inside { ... } to run commands inside a Docker container. This lets you run build steps in a clean, isolated environment using the specified Docker image.

Syntax

The basic syntax to use a Docker image in a Jenkins Pipeline is:

• docker.image('image_name'): Selects the Docker image to use.
• .inside { ... }: Runs the enclosed steps inside a container of the selected image.

groovy

docker.image('image_name').inside {
    // commands to run inside the container
}

Example

This example shows how to run shell commands inside an alpine Docker container in a Jenkins Pipeline.

groovy

pipeline {
    agent any
    stages {
        stage('Run in Docker') {
            steps {
                script {
                    docker.image('alpine:3.18').inside {
                        sh 'echo Hello from inside the Alpine container'
                        sh 'apk add --no-cache curl'
                        sh 'curl --version'
                    }
                }
            }
        }
    }
}

Output

Hello from inside the Alpine container
curl 8.2.1 (x86_64-alpine-linux-musl) libcurl/8.2.1 OpenSSL/3.1.2 zlib/1.2.13 brotli/1.0.9 libidn2/2.3.4 libssh2/1.11.0 nghttp2/1.52.0 librtmp/2.3

Common Pitfalls

Common mistakes when using docker.image in Jenkins Pipeline include:

• Not having Docker installed or configured on the Jenkins agent.
• Using docker.image outside a script block in declarative pipelines, causing syntax errors.
• Forgetting to pull the image first if it is not available locally.
• Running commands that require root privileges without proper permissions inside the container.

groovy

/* Wrong: Using docker.image outside script block in declarative pipeline */
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                docker.image('alpine').inside {
                    sh 'echo This will fail'
                }
            }
        }
    }
}

/* Right: Wrap docker.image usage inside script block */
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                script {
                    docker.image('alpine').inside {
                        sh 'echo This works'
                    }
                }
            }
        }
    }
}

Quick Reference

Tips for using docker.image in Jenkins Pipeline:

• Always use script block when calling docker.image in declarative pipelines.
• Use specific image tags to avoid unexpected updates.
• Ensure Docker daemon is accessible by Jenkins agent.
• Use .inside to run commands inside the container, or .run for detached containers.

Key Takeaways

Use docker.image('name').inside { ... } to run pipeline steps inside a Docker container.

Wrap docker.image calls inside script blocks in declarative pipelines to avoid syntax errors.

Make sure Docker is installed and accessible on the Jenkins agent running the pipeline.

Specify exact image tags to ensure consistent builds.

Use .inside for running commands inside containers and .run for detached container execution.