This article extends the discussion about passing data between nodes in Jenkins pipelines, focusing on a key mechanism: stash and unstash.

While stash is commonly used in distributed pipelines, many engineers are unaware of its storage location, performance characteristics, and practical limits. Understanding these details is critical when designing scalable CI/CD pipelines.

1. What stash Actually Does

The stash step temporarily stores files produced during a stage so they can be restored later in the pipeline.

Example:

stage('Build') {
    steps {
        sh "mkdir dist"
        sh "echo artifact > dist/app.txt"

        stash name: "build-artifact", includes: "dist/*"
    }
}

stage('Deploy') {
    steps {
        unstash "build-artifact"
        sh "cat dist/app.txt"
    }
}

stage('Build') {
    steps {
        sh "mkdir dist"
        sh "echo artifact > dist/app.txt"

        stash name: "build-artifact", includes: "dist/*"
    }
}

stage('Deploy') {
    steps {
        unstash "build-artifact"
        sh "cat dist/app.txt"
    }
}

At first glance, this appears to simply move files between stages. Internally, however, Jenkins performs several operations.

2. Internal Workflow of stash

When stash is executed, Jenkins performs the following steps:

More precisely:

1. Files matching the includes pattern are collected from the workspace.
2. Jenkins compresses them into a TAR archive.
3. The archive is sent from the agent to the Jenkins controller.
4. The controller stores the archive temporarily.
5. When unstash is called, the archive is sent to the target node.
6. Files are extracted into the new workspace.

This mechanism allows pipelines to safely transfer files even if the stages execute on completely different machines.

3. Where Stashed Data Is Stored

Contrary to what many users assume, stashed files are not stored on the agent that created them.

They are stored on the Jenkins controller inside the build directory.

Typical location:

$JENKINS_HOME/jobs/<job-name>/builds/<build-number>/stashes/

$JENKINS_HOME/jobs/<job-name>/builds/<build-number>/stashes/

Example:

/var/lib/jenkins/jobs/my-pipeline/builds/152/stashes/

/var/lib/jenkins/jobs/my-pipeline/builds/152/stashes/

Each stash is saved as a compressed archive.

This explains two important characteristics:

• stash survives agent changes
• the controller handles the storage and transfer

However, this design also introduces performance considerations.

4. Why Large Stashes Are a Problem

Because stashes are routed through the controller, they can overload the system when large files are transferred.

The process looks like this: Agent -> Controller -> Agent

Instead of: Agent -> Agent

This means the controller becomes a bottleneck.

Potential consequences include:

• increased controller CPU usage
• slower pipelines
• disk pressure on $JENKINS_HOME
• slower build queues

For this reason, Jenkins documentation strongly advises not using stash for large artifacts.

5. Practical Size Limits

Technically, Jenkins does not enforce a strict hard limit on stash size.

However, in practice the following guidelines are widely used:

Large artifacts should instead be stored in artifact repositories or object storage systems.

6. Why Jenkins Uses the Controller as the Transfer Hub

Jenkins was designed as a controller-agent architecture.

Agents are intentionally isolated from each other: Agent A cannot directly access Agent B

This design improves:

• security
• network isolation
• infrastructure flexibility

The controller acts as a central coordination point.

While this simplifies orchestration, it also means that transferring data between agents requires the controller to intermediate.

7. Configuring Stash Behavior

Most Jenkins installations use default stash behavior, but several configuration options exist.

Pipeline Option: Preserve Stashes

When restarting pipelines, stashes may be required again.

Example:

options {
    preserveStashes()
}

options {
    preserveStashes()
}

This ensures stashes remain available if the pipeline is restarted from a checkpoint.

Controller Disk Usage

Since stashes are stored inside $JENKINS_HOME, controller disk capacity becomes important.

Administrators should monitor: $JENKINS_HOME especially in systems with large pipelines.

Build Retention Policies

Stashes are removed when the build is deleted.

Retention is typically managed using:

options {
    buildDiscarder(logRotator(numToKeepStr: '30'))
}

options {
    buildDiscarder(logRotator(numToKeepStr: '30'))
}

Reducing the number of retained builds also cleans old stashes.

8. Performance Considerations

In large CI/CD systems, heavy use of stash can cause performance problems.

Key factors include:

• controller disk speed
• controller CPU usage
• network latency between agents and controller
• stash size
• stash frequency

For example:

• pipeline with 20 stages
• each stage stashes 80MB

This can easily generate several gigabytes of data transfer per build.

9. Alternatives to stash

When artifacts are large or persistent storage is required, external systems should be used instead.

Common alternatives include:

Artifact Repositories

Examples:

• Nexus
• Artifactory

Example workflow:

Object Storage

Examples:

• Amazon S3
• Google Cloud Storage
• Azure Blob Storage

Example pipeline:

stage('Upload Artifact') {
    steps {
        sh "aws s3 cp dist/app.jar s3://ci-artifacts/app.jar"
    }
}

stage('Deploy') {
    steps {
        sh "aws s3 cp s3://ci-artifacts/app.jar app.jar"
        sh "deploy app.jar"
    }
}

stage('Upload Artifact') {
    steps {
        sh "aws s3 cp dist/app.jar s3://ci-artifacts/app.jar"
    }
}

stage('Deploy') {
    steps {
        sh "aws s3 cp s3://ci-artifacts/app.jar app.jar"
        sh "deploy app.jar"
    }
}

This approach scales far better for large artifacts.

10. When to Use stash

stash works best for small intermediate files needed within the same pipeline execution.

Typical examples include:

• compiled binaries
• generated configuration files
• test reports
• packaged Helm charts
• temporary build outputs

11. When Not to Use stash

Avoid using stash when dealing with:

• Docker images
• large build artifacts
• multi-gigabyte files
• long-term artifact storage

In these cases, external storage systems are the correct solution.

12. Best Practices

Reliable Jenkins pipelines follow several guidelines.

Keep stashes small

Only transfer the files required by later stages.

Use precise include patterns

Example:

stash name: "build", includes: "dist/app.jar"

stash name: "build", includes: "dist/app.jar"

instead of:

stash name: "build", includes: "**/*"

stash name: "build", includes: "**/*"

Monitor controller disk usage

Since stashes live in $JENKINS_HOME, controller disk performance directly affects pipeline performance.

Use artifact repositories for large builds

Large artifacts should bypass Jenkins entirely.

13. Summary

The stash mechanism is a powerful tool for transferring files between nodes in Jenkins pipelines.

However, it works by storing compressed archives on the Jenkins controller, which introduces performance and scalability considerations.

Understanding where stashes are stored, how they are transferred, and when they should be avoided helps engineers design efficient pipelines.

When used correctly, stash is ideal for transferring small intermediate artifacts between distributed stages. For larger files, external artifact storage systems provide a more scalable and reliable solution.