Stash and Unstash

In this lesson you will learn how to use the Jenkins stash and unstash Pipeline steps to move files between stages within a single pipeline run. This technique is commonly used to cache build artifacts or dependency directories (for example, node_modules) so later stages, possibly running on different agents, can reuse them without repeating expensive operations.

stash archives a set of files from the current workspace so they can be restored later in another stage of the same pipeline run.
unstash restores a previously created stash by name into the current workspace.
By default, stashes are discarded at the end of the pipeline run. Use persistent artifact storage (or plugins that support retention) if you need data to persist across separate runs.

A screenshot of the Jenkins documentation page describing the "stash" Pipeline step. The page shows the heading "stash: Stash some files to be used later in the build," explanatory text and option fields on the right, and a User Handbook navigation sidebar on the left.

Stashes are specific to a single pipeline run. If you want to retain artifacts between runs, consider using persistent artifact storage or plugins that support preserving stashes.

Typical workflow

Install dependencies or create artifacts in an early stage.
stash the produced files (e.g., node_modules/**) immediately after they are created.
unstash the named stash in a later stage, even if that stage runs on a different agent.
Continue with tests or other tasks using the restored files.

Example stash invocation (simple snippet):

stash(includes: 'node_modules/**', name: 'solar-system-node-modules')

Example: Node.js pipeline before and after stashing

Initial Jenkinsfile fragment (before stashing):

stage('NodeJS 20') {
    agent { label 'nodejs-agent' }
    stages {
        stage ('Install Dependencies') {
            options { retry(2) }
            steps {
                sh 'node -v'
                sh 'npm install --no-audit'
            }
        }

        stage ('Testing') {
            steps {
                sh 'node -v'
                sh 'npm test'
            }
        }
    }
}

Add the stash immediately after npm install so the installed dependencies are archived for later stages:

stage('NodeJS 20') {
    agent { label 'nodejs-agent' }
    stages {
        stage ('Install Dependencies') {
            options { retry(2) }
            steps {
                sh 'node -v'
                sh 'npm install --no-audit'
                stash(includes: 'node_modules/**', name: 'solar-system-node-modules')
            }
        }

        stage ('Testing') {
            steps {
                sh 'node -v'
                // restore node_modules from the stash
                unstash 'solar-system-node-modules'
                sh 'npm test'
            }
        }
    }
}

If you prefer the later stage to skip npm install entirely and rely solely on the previously stashed node_modules, remove the install step and unstash instead:

stage ('Install Dependencies (Sequential)') {
    options { retry(2) }
    steps {
        sh 'node -v'
        // Use previously stashed node_modules instead of npm install
        unstash 'solar-system-node-modules'
    }
}

Console output (example excerpts)

From the stage that creates the stash:

Installing Dependencies - 9s
Check out from version control
nodejs-22-6-0 — Use a tool from a predefined Tool Installation 3s
node -v — Shell Script <1s
npm install --no-audit — Shell Script 6s
solar-system-node-modules — Stash some files to be used later in the build 3s
stashed 4,898 files successfully

From the stage that restores the stash:

Install Dependencies - <1s
nodejs-22-6-0 — Use a tool from a predefined Tool Installation
node -v — Shell Script
solar-system-node-modules — Restore files previously stashed
restored files previously stashed successfully

Why use stash + unstash

Enables moving files between stages that run on different agents (e.g., different nodes, Docker containers, or Kubernetes pods).
Avoids repeating expensive operations like re-installing dependencies during the same pipeline run.
Keeps workspaces clean by allowing you to store only the required files and restore them on demand.

Quick comparison: stash vs archived artifacts

Feature	`stash`	`archiveArtifacts`
Scope	Single pipeline run	Persists across builds (stored with the build)
Typical use case	Temporary caching between stages/agents	Long-term artifact retention, downloads from build UI
Overhead	Fast, optimized for intra-run transfer	Larger storage usage; intended for release artifacts

Notes and gotchas

Keep your includes/excludes precise. Stash patterns use Ant-style globs (e.g., node_modules/**). Over-broad patterns increase stash size and transfer time.
Stashes are per-run and ephemeral. To reuse artifacts across separate builds, use archiveArtifacts, an external cache, or a plugin that retains stashes.
Some filesystem issues (rename, locking) can surface during install; stashing can help avoid repeating a problematic step within the same run but does not fix the underlying filesystem issue.
If your pipeline creates many or very large stashes, consider using a persistent caching mechanism (artifact repository, shared volume, or build cache) for efficiency.

Stashed files are discarded when the pipeline run finishes. Do not rely on stash for long-term caching across separate builds—use artifact storage or a caching plugin for persistent reuse.

Best practices

Stash only what is necessary (e.g., node_modules/** rather than **).
Name stashes clearly (e.g., solar-system-node-modules) so they are easy to reference in later stages.
Use options { retry(n) } around fragile steps like installs to reduce flakiness before stashing.
Monitor stash sizes and transfer times; large stashes may negate the performance benefits.

Links and references

That’s the essence of using stash and unstash to move files between stages inside the same Jenkins pipeline run—an effective way to cache dependencies and reduce redundant work.

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

Typical workflow

Example: Node.js pipeline before and after stashing

Console output (example excerpts)

Why use stash + unstash

Quick comparison: stash vs archived artifacts

Notes and gotchas

Best practices

Links and references

Watch Video

​Typical workflow

​Example: Node.js pipeline before and after stashing

​Console output (example excerpts)

​Why use stash + unstash

​Quick comparison: stash vs archived artifacts

​Notes and gotchas

​Best practices

​Links and references

Watch Video

Typical workflow

Example: Node.js pipeline before and after stashing

Console output (example excerpts)

Why use stash + unstash

Quick comparison: stash vs archived artifacts

Notes and gotchas

Best practices

Links and references