Skip to main content

Migrating Hudson build jobs from one server to another

Posted by johnsmart on March 14, 2010 at 8:41 PM PDT

Sometimes, you may need to move or copy Hudson build jobs from one Hudson instance to another, without copying the entire Hudson configuration. For example, you might be migrating your build jobs to a Hudson instance on a brand new box, with system configuration details that vary from the original machine.

Hudson stores all of the data it needs for a project in a sub-directory of the 'jobs' directory in $HUDSON_HOME. This sub-directory is easy to identify - it has the same name as your project. Incidently, this is one reason why your project names really shouldn't contain spaces, particularly if Hudson is running under Unix or Linux - it makes maintenance and admin tasks a lot easier if the project names are also well-behaved unix filenames.

You can copy or move build jobs between instances of projects simply enough by copying or moving the build job directories to the 'jobs' directory on the new Hudson instance. A project job directory is self-contained - it contains both the full project configuration and all the build history. It is even safe to copy build job directories to a running Hudson instance, though if you are also deleting them from the original server, you should shut this one down first. You don't even need to restart the new Hudson instance to see the results of your import - just go to the 'Manage Hudson' screen and click on 'Reload Configuration From Disk'. This will load the new jobs and make them immediately visible on the Hudson dashboard.

There are a few gotchas, however. If you are migrating your jobs to a brand new Hudson configuration, remember to install, or migrate, the plugins from your original server. The plugins can be found in the $HUDSON_HOME/plugins directory, so you can simply copy everything from this directory to the corresponding directory in your new instance.

Of course, you might be migrating the build jobs to a new instance precisely because the plugin configuration on the original box is a mess. Hudson plugins can be a bit buggy sometimes, and you may want to move to a clean installation with a well-known, well-defined set of vetted plugins. In this case, you may need to rework some of your project configurations once they have been imported.

The reason for this is straightforward. When you use a plugin in a project, the project's config.xml will be updated with plugin-specific configuration fields. If for some reason you need to migrate projects selectively to a Hudson installation without these plugins installed, Hudson will no longer understand these parts of the project configuration. The same thing can also sometimes happen if the plugin versions are very different on the machines, and the data format used by the plugin has changed.

If you are migrating jobs to a Hudson instance with a different configuration, it also pays to keep an eye on the system logs. Invalid plugin configurations will usually through warnings or exceptions. While not always fatal, these error messages often mean that the plugin will not work as expected, or at all.

Hudson provides some useful features to help you migrate your project configurations. If Hudson finds data that it thinks is out of date or invalid, it will tell you so. On the 'Manage Hudson' screen, you will get a message like the one below:

From here, you can choose to either leave the configuration as it is (just in case you roll back to a previous version of your Hudson instance, for example), or let Hudson discard the fields it cannot read. If you click on the 'Manage' button, Hudson will bring up a screen containing more details about the error, and can even help tidy up your project configuration files if you wish:

This screen gives you more details about the project containing the dodgy data, as well as the exact error message. This gives you several options. If you are sure that you no longer need the plugin that originally created the data, you can safely remove the redundant fields by clicking on the 'Discard Unreadable Data' button. Alternatively, you may decide that the fields belong to a useful plugin that hasn't yet been installed on the new Hudson instance. In this case, install the plugin and all should be well. Finally, you can always choose to leave the redundant data and live with the error message, at least until you are sure that you won't need to migrate the job back to the old server some day.

So, all in all, migrating build jobs between Hudson instances isn't all that hard - you just need to know a couple of tricks for the corner cases, and if you know where to look Hudson provides some nice tools to make the process smoother.

Related Topics >>