March 24, 2008

Versioning a Hudson job configuration

Let’s say you’re using Hudson as your build/Continuous Integration tool. And let’s assume you have some jobs running inside Hudson that you want to keep running, even if the build machine blows up. You probably want to maintain:

  • Hudson itself
  • All the plugins
  • The overall configuration
  • The per-job configuration

Naturally, then, your thoughts should turn to “How do I put the Hudson configuration into source control?” Here’s what you do:

  1. Make sure your builds are configured and working to your satisfaction, in a directory that I will from now on refer to as HUDSON_HOME.
  2. Copy the entire HUDSON_HOME directory tree to a temporary location called “versioned_build”
    1. In the versioned_build directory, you’ll find the jobs directory, and under that, a directory for each job.
    2. Inside each job directory, you’ll find configuration .xml files and other miscellaneous files, and you’ll find two subdirectories:
      • workspace
      • builds
    3. Empty those two subdirectories of all files, but do not delete the subdirectories.
  3. Repeat this “clean out” process for each job.
  4. import the entire “versioned_build” directory tree into source management.

Now, you have your Hudson configuration in source control. You can start it up, and assuming HUDSON_HOME is set right (see below), you should see your dashboard, and your jobs listed, and properly configured.

Issues

  • You may have to manually kick off your jobs to “prime the pump”
  • Your build number will not start at 0 unless you do not archive the nextBuildNumber file
  • Your HUDSON_HOME environment variable may be incorrect for your machine (see below)

HUDSON_HOME Portability

For ease of checkout and maintenance, I like the following directory setup:

$HUDSON_HOME/

  • hudson/
    • hudson.war
  • jobs/
    • Your Hudson Jobs Here
  • plugins/
    • Your Hudson Plugins Here

Using this configuration, you can create a file in $HUDSON_HOME called, say, hudson.sh, which would look a little something like this:


#!/bin/sh

export HUDSON_HOME=.

export CVS_RSH=/usr/bin/ssh

java -jar hudson/hudson.war

Using this structure, and that hudson.sh script (I presume you can do something similar in Windows) gives you the following benefits:

  1. Your entire Hudson system, including the Hudson war file and the launcher script are all maintained as part of the repository.
  2. You don’t have to set HUDSON_HOME whenever you check the system out of source control – it’s already set by default to the current directory. As long as you run hudson.sh in its own directory, you’ll get the correct value for HUDSON_HOME

Learn from my mistakes!

  • Unless you absolutely must, don’t tell Hudson where to find Ant or the JDK. If they’re on your path, Hudson will find them on its own. If you set them for your build machine, chances are that on the checkout machine they won’t be in exactly the same place