Utilize newContainerPerStage

This guide explains why and when to use the newContainerPerStage directive in Jenkins Pipeline. It walks through examples that show the difference between reusing a single container for all stages (the default when using a top-level docker/dockerfile agent) and launching a fresh container per stage with options { newContainerPerStage() }.

When you might run different agents per stage

Often pipelines define different agents at the stage level (for example, a global any agent with a single stage that uses a dockerfile agent). A pipeline that mixes global and per-stage agents can look like this:

pipeline {
  agent any

  stages {
    stage('S1-Any Agent') {
      steps {
        // runs on the global 'any' agent
      }
    }

    stage('S2-Ubuntu Agent') {
      agent { label 'ubuntu' }
      steps {
        // runs on an Ubuntu node
      }
    }

    stage('S3-Docker Image Agent') {
      agent { docker 'node:18-alpine' }
      steps {
        // runs inside docker image
      }
    }

    stage('S4-Dockerfile Agent') {
      agent {
        dockerfile {
          filename 'Dockerfile.cowsay'
          label 'ubuntu-docker-jdk17-node20'
        }
      }
      steps {
        sh 'node -v'
      }
    }
  }
}

In the next sections we demonstrate switching from a mix of per-stage agents to a single top-level Dockerfile-based agent — and how the newContainerPerStage option changes runtime behavior.

Top-level `dockerfile` agent (single container reused for all stages)

If you configure a top-level dockerfile agent, Jenkins will build the image, run a container from that image on the chosen node, and reuse that container for every stage in the pipeline. For example:

pipeline {
  agent {
    dockerfile {
      filename 'Dockerfile.cowsay'
      label 'ubuntu-docker-jdk17-node20'
    }
  }

  stages {
    stage('Stage-1') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
      }
    }

    stage('Stage-2') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
      }
    }

    stage('Stage-3') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
      }
    }

    stage('Stage-4') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
      }
    }
  }
}

When a pipeline runs this way, Jenkins:

Builds the image from the specified Dockerfile (Dockerfile.cowsay).
Starts a single container from that image on the selected node.
Reuses the same container and workspace for all stages.
Stops and removes the container when the pipeline completes.

Screenshot of a Jenkins pipeline page for "pipeline-external-agent" showing multiple build runs with stage progress indicators (mostly green checkmarks) across stages like Checkout SCM, Agent Setup, Stage-1..Stage-4. The left sidebar lists pipeline actions (Status, Changes, Build Now, Configure) and a build history panel.

Controller logs for such a run show the Docker image build and the container start:

[Pipeline] sh
+ docker build -t 0f559f3f6ac2e220b616594d407b50bd36d83f74 -f Dockerfile.cowsay .
#1 [internal] load build definition from Dockerfile.cowsay
#1 DONE 0.0s
#2 [internal] load metadata for docker.io/library/node:18-alpine
#2 DONE 0.0s
#4 [1/2] FROM docker.io/library/node:18-alpine
#4 DONE 0.0s
#5 [2/2] RUN apk update && apk add --no-cache git perl && cd /tmp && git clone https://github.com/jasonm23/cowsay.git && cd cowsay ; ./install.sh /usr/local
#5 CACHED
#6 exporting to image
#6 writing image sha256:d76b723... done
[Pipeline] withDockerContainer
$ docker run -t -d -u 0:0 -w /home/jenkins-agent/workspace/pipeline-external-agent -v /home/jenkins-agent/workspace/pipeline-external-agent:/home/jenkins-agent/workspace/pipeline-external-agent:rw,z 0f559f3f6ac2e220b616594d407b50bd36d83f74 cat

Because the same container and workspace are reused, files written by one stage to the container filesystem (for example, /tmp) will still be present for subsequent stages. Example pipeline that writes and reads a transient file:

pipeline {
  agent {
    dockerfile {
      filename 'Dockerfile.cowsay'
    }
  }

  stages {
    stage('Stage-1') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
        echo "********************************************************************************************************"
        sh 'echo $((RANDOM)) > /tmp/imp-file-$BUILD_ID'
        sh 'ls -ltr /tmp/imp-file-$BUILD_ID'
        sh 'cat /tmp/imp-file-$BUILD_ID'
        echo "********************************************************************************************************"
      }
    }

    stage('Stage-2') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
        echo "####################################################################################################"
        sh 'ls -ltr /tmp/imp-file-$BUILD_ID'
        sh 'cat /tmp/imp-file-$BUILD_ID'
        echo "####################################################################################################"
      }
    }

    stage('Stage-3') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
        echo "####################################################################################################"
        sh 'ls -ltr /tmp/imp-file-$BUILD_ID'
        sh 'cat /tmp/imp-file-$BUILD_ID'
        echo "####################################################################################################"
      }
    }

    stage('Stage-4') {
      steps {
        sh 'node -v'
        sh 'npm -v'
        sh 'cowsay -f dragon This is running on Docker Container'
        echo "########################################################################################################"
        sh 'ls -ltr /tmp/imp-file-$BUILD_ID'
        sh 'cat /tmp/imp-file-$BUILD_ID'
        echo "########################################################################################################"
        sh 'sleep 120s' // keep container alive briefly for demo
      }
    }
  }
}

Trimmed logs (showing the same random number read across stages):

+ ls -ltr /tmp/imp-file-7
-rw-r--r-- 1 109 112 5 Nov 10 07:42 /tmp/imp-file-7
+ cat /tmp/imp-file-7
7577

...

+ cat /tmp/imp-file-7
7577

While the Stage-4 sleep keeps the container alive, you can confirm the file exists by inspecting the container on the controller:

$ docker ps
CONTAINER ID   IMAGE                                      STATUS
d1ae29e5fc61   0f559f3f6ac2...                            Up About a minute

$ docker exec -it d1ae29e5fc61 sh
/var/lib/jenkins/workspace/pipeline-external-agent $ cat /tmp/imp-file-7
7577

Isolated containers per stage with `newContainerPerStage()`

If you need strict isolation between stages — for example, to ensure no filesystem state is carried over — use the newContainerPerStage() option. When applied together with a top-level dockerfile (or docker) agent, Jenkins will create a fresh container for each stage using the same image definition.

Using options { newContainerPerStage() } makes Jenkins run each stage in a brand-new container created from the same Dockerfile. Files written to the container filesystem in one stage will not be visible in subsequent stages.

Example pipeline with newContainerPerStage():

pipeline {
  agent {
    dockerfile {
      filename 'Dockerfile.cowsay'
    }
  }

  options {
    newContainerPerStage()
  }

  stages {
    stage('Stage-1') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
        sh 'echo $((RANDOM)) > /tmp/imp-file-$BUILD_ID'
        sh 'ls -ltr /tmp/imp-file-$BUILD_ID'
        sh 'cat /tmp/imp-file-$BUILD_ID'
      }
    }

    stage('Stage-2') {
      steps {
        sh 'cat /etc/os-release'
        sh 'node -v'
        sh 'npm -v'
        sh 'ls -ltr /tmp/imp-file-$BUILD_ID'
        sh 'cat /tmp/imp-file-$BUILD_ID'
      }
    }
  }
}

Note: The ls and cat calls in Stage-2 will typically fail because those files were created in the previous stage’s container, not the current one. When newContainerPerStage() is enabled, you will observe:

Jenkins builds (or validates) the image and runs a new container for each stage.
Files created inside one stage’s container are not present in the next stage’s container.
Expect No such file or directory errors when trying to access stage-local files created previously.

Example trimmed failure log from Stage-2:

+ docker build -t 0f559f3f6ac2e220b... -f Dockerfile.cowsay .
$ docker run -t -d ... 0f559f3f6ac2e220b... cat
+ ls -ltr /tmp/imp-file-8
ls: /tmp/imp-file-8: No such file or directory

Quick comparison

Behavior	Top-level `dockerfile` agent (default)	`options { newContainerPerStage() }`
Containers created	Single container created and reused	New container created for each stage
Filesystem sharing	Yes — files persist between stages	No — each container has a fresh filesystem
Use case	When stages need to share transient data (fast local persistence)	When you want strict stage isolation to avoid state carryover
Node requirement	Runs on the same node	Runs on the same node (different containers)

Summary

A top-level dockerfile or docker agent builds the image and reuses a single container and workspace across all stages. Useful when you want to share files or state via the container filesystem.
options { newContainerPerStage() } forces Jenkins to create a fresh container for each stage (using the same image definition). Use this when you need strict isolation between stages and want to avoid accidental state carryover.
Choose the mode that matches your pipeline needs: inter-stage filesystem sharing vs. per-stage isolation.

Shared Libraries in Jenkins

Agents and Nodes in Jenkins

Pipeline Enhancement and Caching

Pipeline Structure and Scripted vs Declarative

Jenkins Administration and Monitoring

Backup and Configuration Management

Introduction

Utilize newContainerPerStage

When you might run different agents per stage

Top-level `dockerfile` agent (single container reused for all stages)

Isolated containers per stage with `newContainerPerStage()`

Quick comparison

Summary

Links and references

Watch Video

Practice Lab

​When you might run different agents per stage

​Top-level dockerfile agent (single container reused for all stages)

​Sharing files via the container filesystem

​Isolated containers per stage with newContainerPerStage()

​Quick comparison

​Summary

​Links and references

Watch Video

Practice Lab

When you might run different agents per stage

Top-level `dockerfile` agent (single container reused for all stages)

Sharing files via the container filesystem

Isolated containers per stage with `newContainerPerStage()`

Quick comparison

Summary

Links and references