Stash and unstash for passing data in Jenkins - Step-by-Step Execution

Process Flow - Stash and unstash for passing data

Start Pipeline

↓

Stash files

↓

Move to another stage

↓

Unstash files

↓

Use files in new stage

↓

Pipeline continues or ends

This flow shows how Jenkins saves files with stash, then retrieves them later with unstash to share data between pipeline stages.

Execution Sample

Jenkins

stage('Build') {
  stash name: 'app', includes: '**/*.jar'
}
stage('Test') {
  unstash 'app'
  sh 'java -jar app.jar'
}

This Jenkins pipeline stashes jar files in the Build stage, then unstashes and runs them in the Test stage.

Process Table

Step	Action	Files Affected	Pipeline Stage	Result
1	Start Build stage	none	Build	Build stage begins
2	Stash files named 'app'	*.jar files	Build	Files saved for later stages
3	End Build stage	none	Build	Build stage ends
4	Start Test stage	none	Test	Test stage begins
5	Unstash files named 'app'	*.jar files	Test	Files restored for use
6	Run 'java -jar app.jar'	app.jar	Test	Application runs using unstashed files
7	End Test stage	none	Test	Test stage ends
8	Pipeline ends	none	Pipeline	All stages complete

💡 Pipeline ends after all stages complete and files are passed via stash/unstash

Status Tracker

Variable	Start	After Step 2	After Step 5	Final
Stash 'app'	empty	*.jar files saved	files restored	files used in Test stage

Key Moments - 3 Insights

Why do we need to stash files in one stage and unstash in another?

Because each Jenkins stage runs in a separate workspace, stashing saves files so they can be restored later in a different stage, as shown in steps 2 and 5.

What happens if you try to unstash files that were never stashed?

The pipeline will fail at the unstash step (step 5) because there are no saved files with that stash name, causing an error.

Does unstashing overwrite existing files in the workspace?

Yes, unstashing restores files and can overwrite files with the same name in the current workspace, as seen when files are restored in step 5.

Visual Quiz - 3 Questions

Look at the execution table, what files are saved during the stash step?

A *.jar files

B No files

C *.txt files

D All files

💡 Hint

Check Step 2 in the execution table where stash saves files.

At which step does the pipeline restore the stashed files?

A Step 7

B Step 2

C Step 5

D Step 1

💡 Hint

Look for the unstash action in the execution table.

If the stash name was changed in the unstash step to 'app2', what would happen?

A Files would still be restored

B Pipeline would fail at unstash

C Files would be partially restored

D Pipeline would skip unstash silently

💡 Hint

Refer to key moment about unstashing files that were never stashed.

Concept Snapshot

Jenkins stash saves files in one stage for later use.
Unstash restores those files in another stage.
Use stash name to identify files.
Each stage has separate workspace.
Stash/unstash passes data between stages safely.

Full Transcript

This visual execution shows how Jenkins pipelines use stash and unstash to pass files between stages. First, files matching a pattern are saved with stash in the Build stage. Then, in the Test stage, unstash restores those files so they can be used. Each step is tracked showing when files are saved, restored, and used. Key points include that stash is needed because each stage runs separately, unstash requires the correct stash name, and unstashing overwrites files in the workspace. The quiz tests understanding of when files are saved and restored and what happens if names don't match. This helps beginners see the step-by-step flow of passing data in Jenkins pipelines.

Practice

1. What is the main purpose of stash and unstash in Jenkins pipelines?

easy

A. To temporarily save and later restore files between pipeline stages

B. To permanently store files on the Jenkins master server

C. To delete files after a pipeline stage completes

D. To send notifications when a stage finishes

Solution

1. Step 1: Understand the role of stash

   The stash command saves files temporarily during a pipeline run.

2. Step 2: Understand the role of unstash

   The unstash command restores those saved files in later stages or nodes.

3. Final Answer:

   To temporarily save and later restore files between pipeline stages -> Option A

4. Quick Check:

   stash + unstash = temporary file sharing [OK]

Hint: Remember stash saves, unstash restores files between stages [OK]

Common Mistakes:

• Thinking stash permanently stores files
• Confusing stash with deleting files
• Assuming stash sends notifications

2. Which of the following is the correct syntax to stash files named output.log in a Jenkins pipeline?

easy

A. stash { name: 'logs', files: 'output.log' }

B. stash('logs', 'output.log')

C. stash name = 'logs' include = 'output.log'

D. stash name: 'logs', includes: 'output.log'

Solution

1. Step 1: Recall stash syntax

   The correct stash syntax uses named parameters: stash name: '...', includes: '...'.

2. Step 2: Match options to syntax

   stash name: 'logs', includes: 'output.log' matches the correct syntax exactly.

3. Final Answer:

   stash name: 'logs', includes: 'output.log' -> Option D

4. Quick Check:

   stash uses named params: name and includes [OK]

Hint: Use named parameters: name and includes for stash [OK]

Common Mistakes:

• Using parentheses like a function call
• Using incorrect parameter names like files
• Using assignment (=) instead of colon (:)

3. Given this Jenkins pipeline snippet:

stage('Build') {
  steps {
    sh 'echo Hello > message.txt'
    stash name: 'msg', includes: 'message.txt'
  }
}
stage('Test') {
  steps {
    unstash 'msg'
    sh 'cat message.txt'
  }
}

What will be the output of the cat message.txt command in the Test stage?

medium

A. Hello

B. No such file or directory

C. Empty output

D. Error: stash not found

Solution

1. Step 1: Understand stash saves message.txt

   The Build stage creates message.txt with content 'Hello' and stashes it as 'msg'.

2. Step 2: Unstash restores message.txt in Test stage

   The Test stage unstashes 'msg', restoring message.txt, then runs cat message.txt.

3. Final Answer:

   Hello -> Option A

4. Quick Check:

   unstash restores files, so cat shows 'Hello' [OK]

Hint: Unstash restores files exactly as stashed [OK]

Common Mistakes:

• Assuming unstash does not restore files
• Expecting an error because stages run separately
• Thinking stash deletes files

4. You wrote this Jenkins pipeline snippet:

stage('Build') {
  agent { label 'build' }
  steps {
    sh 'touch file.txt'
    stash name: 'data', includes: 'file.txt'
  }
}
stage('Deploy') {
  agent { label 'deploy' }
  steps {
    unstash 'artifacts'
    sh 'cat file.txt'
  }
}

But the Deploy stage fails with cat: file.txt: No such file or directory. What is the most likely cause?

medium

A. The unstash command is missing in the Deploy stage

B. The file.txt was not created before stashing

C. The stash name used in unstash does not match the stash name

D. The pipeline syntax for stash is incorrect

Solution

1. Step 1: Check stash and unstash names

   The stash is named 'data' but unstash uses 'artifacts', so names do not match.

2. Step 2: Verify file creation and stash syntax

   file.txt is created before stash, unstash command is present, and stash syntax looks correct. Different agents require proper stash/unstash to pass files.

3. Step 3: Identify the cause

   Mismatched names cause unstash to fail silently, so file.txt is not available in Deploy workspace.

4. Final Answer:

   The stash name used in unstash does not match the stash name -> Option C

5. Quick Check:

   stash and unstash names must match exactly [OK]

Hint: Check stash and unstash names match exactly [OK]

Common Mistakes:

• Using different names in stash and unstash
• Forgetting to create the file before stash
• Omitting unstash command in later stage

5. You want to pass multiple files from a Build stage to a Test stage in Jenkins. Which is the best way to stash and unstash these files?

hard

A. stash name: 'allFiles', includes: '*.log, *.txt'
...
unstash 'allFiles'

B. stash name: 'allFiles', includes: '**/*.log, **/*.txt'
...
unstash 'allFiles'

C. stash name: 'allFiles', includes: '**/*.log **/*.txt'
...
unstash 'allFiles'

D. stash name: 'allFiles', includes: '*.log *.txt'
...
unstash 'allFiles'

Solution

1. Step 1: Understand includes pattern syntax

   Jenkins stash supports comma-separated glob patterns with '**/' for recursive matching.

2. Step 2: Compare options

   stash name: 'allFiles', includes: '**/*.log, **/*.txt' ... unstash 'allFiles' uses comma-separated recursive globs, which is correct. Options A, B, and C either lack recursion (A, B) or use spaces instead of commas (B, C). For example, '**/*.log **/*.txt' misses comma separator.

3. Final Answer:

   stash name: 'allFiles', includes: '**/*.log, **/*.txt' ... unstash 'allFiles' -> Option B

4. Quick Check:

   Use comma-separated globs with '**/' for multiple file types [OK]

Hint: Use comma-separated globs with '**/' for multiple files [OK]

Common Mistakes:

• Using spaces instead of commas to separate globs
• Missing recursive '**/' causing files to be skipped
• Incorrect glob syntax causing no files to stash