1. Overview
Jenkins workspace is a storage location where a build stores its related files. It is used by successive builds of the same job so we might need to clean it up frequently to avoid conflicting files or output artifacts.
In this tutorial, we’ll cover different ways that we can clean up the workspace of a Jenkins job.
2. What’s a Jenkins Workspace
Jenkins workspace is a directory created on the node where a job is executing. It stores files related to a running build like source code, output artifacts, or a Dockerfile. It is the storage space that the build uses to execute different tasks.
Each job has a separate workspace on the Jenkins node. The path to the workspace directory follows the job name structure. For example, if we created a job with the name test-job under a folder name test-folder, then the workspace directory will be /{Jenkins root directory on the node}/workspace/test-folder/test-job:
$ pwd
/var/lib/jenkins/workspace
$ ls
test-folder
$ cd test-folder/
$ ls
test-job
$ cd test-job/
$ pwd
/var/lib/jenkins/workspace/test-folder/test-job
In this example, the Jenkins root directory on the node is /var/lib/jenkins. So as we can see, the path of the workspace is /var/lib/jenkins/workspace/test-folder/test-job.
Now let’s configure our job to create a file:
pipeline {
agent any
stages {
stage("create file"){
steps{
script {
sh "touch myfile.txt"
}
}
}
}
}
If we trigger our job and check the workspace now we should see the file there:
$ pwd
/var/lib/jenkins/workspace/test-folder/test-job
$ ls
myfile.txt
So now we can work with files and persist data to our workspace from our job.
3. Cleaning the Workspace Using deleteDir Step
The first method to clean the workspace directory is to use the deleteDir step. The deleteDir is part of the workflow basic steps plugin which probably comes installed by default so we don’t need to install it. When we add the deleteDir step to our job it removes any files from the current directory. So if we’re running the stage in the default workspace directory it will clean it up:
stage("clean workspace") {
steps {
script {
sh "ls"
deleteDir()
sh "ls"
}
}
}
Here we added another stage to our previous job. We list the contents of the workspace using the ls command before and after the deleteDir() step to see the difference.
Now let’s trigger the job and check the output:
...
+ touch myfile.txt
[Pipeline] sh
+ ls
myfile.txt
[Pipeline] deleteDir
[Pipeline] sh
+ ls
...
As we can see, the first ls command shows the file in the workspace, however, the second ls command after the deleteDir step is showing no content.
4. Cleaning the Workspace Using cleanWs Step
Another simple method to clean the workspace directory is by using the cleanWs step. The cleanWs is part of the workspace cleanup plugin. We’ll need to install this plugin manually before using the step.
We can install this plugin from the Jenkins available plugins menu:
After installing the plugin, we can start using the cleanWs step in the job.
In our example, we’ll replace the previous deleteDir step with the cleanWs step:
stage("clean workspace") {
steps {
script {
sh "ls"
cleanWs()
sh "ls"
}
}
}
Now let’s check the output of the job:
...
+ touch myfile.txt
[Pipeline] sh
+ ls
myfile.txt
[Pipeline] cleanWs
[Pipeline] sh
+ ls
...
Again we can see the same results as the previous example. The first ls command shows the file in the workspace, while the second ls command after the cleanWs step shows no content.
5. Cleaning the Workspace Using rm Command
One of the very handy options of Jenkins is that you can use the native commands of the node operating system inside the job. For example, if you’re executing the job on a Linux node you can use bash shell commands, or if it’s a Windows node you can use batch commands.
So in our example, if we don’t prefer using plugins we can simply use the Linux rm command to clean the workspace directory:
stage("clean workspace") {
steps {
script {
sh "ls"
sh "rm *"
sh "ls"
}
}
}
Here we used the * wildcard to match any files in the workspace, but we can manipulate the command options as we want.
Now let’s trigger our job and see the results:
...
+ touch myfile.txt
[Pipeline] sh
+ ls
myfile.txt
[Pipeline] sh
+ rm myfile.txt
[Pipeline] sh
+ ls
...
As we can see, the file in the workspace appears after the first ls command and it was removed by the rm command and the workspace is showing no content.
6. Conclusion
In this article, we’ve covered the basics of Jenkins workspace and how to clean its storage.
The Jenkins workspace is a directory on the node that stores files related to a job. Because the workspace is used by successive builds of the same job, we might need to clean it up to avoid any conflict in the stored files.
We can clean up the workspace by using the deleteDir step, which removes the contents of the current directory. Another method to clean up the workspace is by using the cleanWs step, which checks the workspace of the job and deletes data inside it. Finally, if we don’t prefer using plugins we can use the native Linux rm command to delete files in the workspace.