Stash and unstash for passing data in Jenkins - Commands & Configuration

Introduction

When running Jenkins pipelines, sometimes you need to save files or data from one part of the pipeline and use them later in another part. Stash and unstash let you do this easily by temporarily storing files and then retrieving them when needed.

When you want to save build artifacts from one stage to use in a later stage.

When you need to share files between parallel branches in a pipeline.

When you want to pass test reports generated in one step to a publishing step.

When your pipeline runs on different agents and you need to move files between them.

When you want to keep your workspace clean but still keep important files accessible.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        echo 'Building the project'
        sh 'echo Hello World > greeting.txt'
        stash name: 'greetingFiles', includes: 'greeting.txt'
      }
    }
    stage('Test') {
      steps {
        unstash 'greetingFiles'
        sh 'cat greeting.txt'
      }
    }
  }
}

This Jenkinsfile defines a pipeline with two stages: Build and Test.

In the Build stage, it creates a file named greeting.txt and then stashes it with the name greetingFiles. This saves the file temporarily.

In the Test stage, it unstashes the saved files named greetingFiles, making greeting.txt available again, then prints its content.

Commands

Check that Jenkins CLI or Jenkins Job Builder is installed and accessible before running pipelines.

Terminal

jenkins-jobs --version

Expected Output

jenkins-jobs 3.0.0

Run the Jenkinsfile pipeline locally or on a Jenkins server to execute the stages and test stash/unstash functionality.

Terminal

jenkinsfile-runner -w . -p plugins -f Jenkinsfile

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] stage

[Pipeline] { (Build)

[Pipeline] echo

Building the project

[Pipeline] sh

+ echo Hello World > greeting.txt

[Pipeline] stash

Stashing files with name greetingFiles

[Pipeline] }

[Pipeline] stage

[Pipeline] { (Test)

[Pipeline] unstash

Unstashing files with name greetingFiles

[Pipeline] sh

+ cat greeting.txt

Hello World

[Pipeline] }

[Pipeline] End of Pipeline

Key Concept

If you remember nothing else from this pattern, remember: stash saves files temporarily in one stage, and unstash retrieves them in another stage to share data across pipeline steps.

Common Mistakes

Using unstash with a name that was never stashed.

Jenkins will fail the pipeline because it cannot find the stash with that name.

Always use the exact stash name used in the stash step when calling unstash.

Stashing files that do not exist or are not included by the pattern.

The stash will be empty or missing files, causing errors or missing data later.

Ensure the files exist and the include pattern matches the files you want to stash.

Trying to unstash files in the same stage without stashing first.

Unstash only works for files saved in previous stages or parallel branches, not in the same step.

Use stash in one stage and unstash in a later stage or parallel branch.

Summary

Use stash to save files temporarily during a pipeline stage.

Use unstash to retrieve those files in a later stage or parallel branch.

This helps pass data between different parts of a Jenkins pipeline running on different agents or at different times.