Thursday, February 9, 2012

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.


Trinition said...

I didn't know pointing to a new workspace would be so easy! I should've guessed because everything in Jenkins is pretty slick. And this blog gave me the courage to charge ahead without caution.

Ingo Richter said...

Great to hear that this was helpful to you.

Michael Pemulis said...


I had some trouble with this on Windows because the build job was a Maven project and ITEM_FULLNAME was expanding to a path with a component named "groupId:artifactId", which Windows rejected (due to the illegal colon character).

Found this issue, the comments of which were helpful:

The advice is to use ITEM_FULL_NAME instead of ITEM_FULLNAME.

Roberto Prevato said...

After changing the workspace and build directories, using the Jenkins interface, my jobs are not starting anymore. They stay in pending state, with message "pending - waiting for next executor". I tried to revert the change to the default value; but it doesn't work. I verified that the number of executors didn't change: it's still 2, like it used to be. I am using Windows; and after changing the configuration, Jenkins created automatically those directories, with links to the previous ones. Can anybody help me with this?

Roberto Prevato said...

I managed to resolve the problem using the Jenkins web interface, by doing the following:
1 Going to the Jenkins configuration and clicking on the button "Reload configuration from disk";
2 Going to the build executor status page; I noticed that the master was in "dead" state; I clicked on its name and it changed to Idle

I am not sure which of the two things resolved the problem; but the problem definitely happened after I changed the configuration.

viral shah said...

I m archiving my builds . is there anyway i can change the location for it ?

Jake Leveroni said...

Does anyone know if it is possible to have the Jenkins access its jobs if they're stored in an aws s3 bucket?

Ingo Richter said...

I don't know if there is a way to specify the archive location. Have you had a look at the sources?
I don't think, that there is a way to access the Jenkins job when they are located in S3. Usually jobs have to be located on the local Jenkins install directory.

Prashant Katiyar said...

Nice and helpful blog. Thanks for sharing this valuable knowledge Business Directory Listing India, Local Business Listing.

sra said...

What does this ${ITEM_ROOTDIR}/workspace indicate?I just want to know where this ${ITEM_ROOTDIR}/workspace point outs to specifically.

Promozie said...

Nice Blog,Thanks For Sharing Information.
ABCWorld is Business Centre in Pune Providing fully-furnished and equipped workspace in Pune & commercial office space in pune .

Abcworld said...

ABCWorld is Business Centre in Pune Providing fully-furnished and equipped workspace in Pune & commercial office space in pune .