Jenkins : JENKINS-24380 Migration

JENKINS-24380, which is introduced in 1.597, changes the on-disk layout of build directories.

In Jenkins, each job has a directory under $JENKINS_HOME (such as $JENKINS_HOME/jobs/foo/ for a job named foo).

Prior to JENKINS-24380, this directory contained one directory each per build named according to its timestamp, such as builds/2014-09-15_17-51-46/, that contains all information about that build (including build.xml, log, and more). If this build was number 123, there was also a symlink (or, on some Windows systems, plain text file) named 123 that pointed to 2014-09-15_17-51-46. build.xml listed the <number>123</number>; the timestamp (in the local time zone) was implied by the directory name.

After JENKINS-24380, builds/123/ will be the directory that contains the build. There is no longer a symlink per build. (Special status symlinks such as lastStableBuild remain as before, still pointing to the build number.) build.xml now indicates the <timestamp>, whereas the number is implied by the directory name.

Whenever a newer version of Jenkins starts with an older $JENKINS_HOME, the necessary conversion happens automatically during startup. Old build records are converted to the new layout, with the exception that build.xml also has an <id> field giving an internal identifier used by some plugins to refer to builds (formerly based on the timestamp, defaulting for new builds to be the number).

This change was introduced to resolve a number of longstanding issues. Unfortunately, this migration is backward incompatible, in that if you upgrade to Jenkins ≥1.597, which migrates the data, then later decide to downgrade back to <1.597, then the earlier version of Jenkins will not know how to interpret the new $JENKINS_HOME directory layout. As a result, Jenkins will come up without any build records.

In case you want to downgrade, there is an “unmigrate” script provided to reverse the migration of $JENKINS_HOME. To do this:

  1. Start Jenkins ≥1.597.
  2. Visit http://server/jenkins/JENKINS-24380/ and copy the unmigration instruction.
  3. Shut down Jenkins completely.
  4. Run the command as instructed by the step above.
  5. Start Jenkins <1.597 with the same $JENKINS_HOME.