Jenkins: Change Workspaces and Build Directory Locations

Have you ever wanted to change the location of the workspace directory of a Jenkins job? Not enough space on your hard drive or your hard drive is too slow? Whatever the reason might have been for your wish, there is a simple solution. Every job in Jenkins has a well “hidden”, I mean really not so obvious, setting to modify the Workspace root location of the job. To change this location, you need to configure your job and click on the Advanced… button in the “Advanced Project Options” section.

Advanced Project Options

Once you opened the settings, you will find some more configuration options for your job. Look for the “Use custom workspace” option on the right hand side and check the box.

Specify custom workspace for job

Here is some information that you should consider reading, prior to change the workspace.

Information about custom workspace

Important: The next build will use the new location, but you have to manually relocate all the existing content from the previous location.

Globally Changing the workspace location for all Jobs

In order of changing the workspace for a single job, there is another option in the Jenkins system settings that allows for changing the workspace for every job.
Navigate to Jenkins->Manage Jenkins->Configure System and click on the Advanced Button on the right hand side.

Specify custom workspace and builds directory location

Voilà! This opens up the following options section

Custom workspace and builds directory location

 
Now you can change your workspace and build directory to any other location on your machine. Jenkins provides 3 predefined variables that can be used to specify the new location:

• ${JENKINS_HOME} — Jenkins home directory
• ${ITEM_ROOTDIR} — Root directory of a job for which the workspace is allocated
• ${ITEM_FULLNAME} — ‘/’-separated job name, like “foo/bar”

The default value for the “Workspace Root Directory” is ${ITEM_ROOTDIR}/workspace and for the “Build Record Root Directory” it’s ${ITEM_ROOTDIR}/builds.

Some Notes

Please be aware, that if you change your workspace to a different location, the contents of the “old” workspace directory are not copied over to the new workspace.
Doing this on OSX could require to change the owner of the newly created workspace. So, if you encounter permission issues during your next build, then have a look at the new location.