The Jenkins home directory contains all the details of your Jenkins server configuration, details that you configure in the Manage Jenkins screen. These configuration details are stored in the form of a set of XML files. Much of the core configuration, for example, is stored in the config.xml file. Other tools-specific configuration is stored in other appropriately-named XML files: the details of your Maven installations, for example, are stored in a file called hudson.tasks.Maven.xml . You rarely need to modify these files by hand, though occasionally it can come in handy.

The Jenkins home directory also contains a number of subdirectories (see Figure 3.7, “The Jenkins home directory” ). Not all of the files and directories will be present after a fresh installation, as some are created when required by Jenkins. And if you look at an existing Jenkins installation, you will see additional XML files relating to Jenkins configuration and plugins.

The main directories are described in more detail in Table 3.1, “The Jenkins home directory structure” .

The jobs directory is a crucial part of the Jenkins directory structure, and deserves a bit more attention. You can see an example of a real Jenkins jobs directory in Figure 3.8, “The Jenkins jobs directory” .

This directory contains a subdirectory for each Jenkins build job being managed by this instance of Jenkins. Each job directory in turn contains two subdirectories: builds and workspace , along with some other files. In particular, it contains the build job config.xml file, which contains, as you might expect, the configuration details for this build job. There are also some other files used internally by Jenkins, that you usually wouldn’t touch, such as the nextBuildNumber file (which contains the number that will be assigned to the next build in this build job), as well as symbolic links to the most recent successful build and the last stable one. A successful build is one that does not have any compilation errors. A stable build is a successful build that has passed whatever quality criteria you may have configured, such as unit tests, code coverage and so forth.

Both the build and the workspace directories are important. The workspace directory is where Jenkins builds your project: it contains the source code Jenkins checks out, plus any files generated by the build itself. This workspace is reused for each successive build—there is only ever one workspace directory per project, and the disk space it requires tends to be relatively stable.

The builds directory contains a history of the builds executed for this job. You rarely need to intervene directly in these directories, but it can be useful to know what they contain. You can see a real example of the builds directory in Figure 3.9, “The builds directory” , where three builds have been performed. Jenkins stores build history and artifacts for each build it performs in a directory labeled with a timestamp (“2010-03-12_20-42-05” and so forth in Figure 3.9, “The builds directory” ). It also contains symbolic links with the actual build numbers that point to the build history directories.

Each build directory contains information such as the build result log file, the Subversion revision number used for this build (if you are using Subversion), the changes that triggered this build, and any other data or metrics that you have asked Jenkins to keep track of. For example, if your build job keeps track of unit test results or test coverage metrics, this data will be stored here for each build. The build directory also contains any artifacts you are storing—binary artifacts, but also other generated files such as javadoc or code coverage metrics. Some types of build jobs, such as the Jenkins Maven build jobs, will also archive binary artifacts by default.

The size of the build directory will naturally grow over time, as the build history cumulates. You will probably want to take this into account when designing your build server directory structure, especially if your build server is running in a Unix-style environment with multiple disk partitions. A lot of this data takes the form of text or XML files, which does not consume a large amount of extra space for each build. However, if your build archives some of your build artifacts, such as JAR or WAR files, they too will be stored here. The size of these artifacts should be factored into your disk space requirements. We will see later on how to limit the number of builds stored for a particular build job if space is an issue. Limiting the number of build jobs that Jenkins stores is always a trade-off between disk space and keeping useful build statistics, as Jenkins does rely on this build history for its powerful reporting features.

Jenkins uses the files in this directory extensively to display build history and metrics data, so you should be particularly careful not to delete any of the build history directories without knowing exactly what you are doing.