Using the Jenkins Subversion Plugin

Overview
Git, Mercurial and other distributed software configuration management (SCM) solutions enjoyed great success over this past year, but the large majority of developers still use the classic, de facto standard -- Subversion. Now hosted by the Apache Software Foundation, Subversion 1.7 was released last year with significant improvements. Due to its widespread acceptance, we can rely on a large user base for the foreseeable future. As it does for other SCM solutions, Jenkins has a dedicated plugin to support Subversion, one of the most widely used SCMs. It is part of the core release and provided by default with your Jenkins installation files.

Requirements
The Jenkins Subversion plugin uses SvnKit as the subversion client and doesn't require a native client to be available on the host. Setting up a CI server with Jenkins and Subversion is limited to a very minimal installation process: just run the Jenkins WAR and you're done.

How To ...
When configuring a job with Jenkins Subversion plugin, Jenkins will try to validate the repository URL that was entered. As the repository may require authentication, Jenkins will ask you to enter credentials. Those credentials are stored on your first valid authentication, so it won't bother you for them on your next access. To change the credentials used to access a repository, you can navigate to https://JENKINS/scm/SubversionSCM/enterCredential. Please note: in some circumstances, setting authentication may be a more complex process, especially if you use Kerberos or client certificates.

A Jenkins SCM plugin will:

1. detect changes in the SCM and trigger a new build if needed
2. put the workspace in the desired state for a build to start

The Jenkins Subversion plugin can poll changes from one or multiple repositories, and do some fine filtering for incoming changes. For example, you can select a subset of your repository using include/exclude rules, or filter by user or commit message to ignore some commits if you use automated tools that commit irrelevant changes in the repository.

Multiple repositories, inclusion and exclusion rules can be used to focus on a precise set of changes you want your continuous integration server to monitor. As combinations may be complex, you're encouraged to progressively introduce such rules to exclude irrelevant commits.

When a commit is detected to match all the configured rules, a build is triggered. But this will require your Jenkins server to actively poll Subversion for changes. If you already have read this article on our blog, you know that an active triggering from the SCM can be far more efficient for Jenkins to immediately start a build on a commit and not unnecessarily consume server resources for polling. As with most SCM plugins, the Jenkins Subversion plugin can use this strategy to be notified on commit. The plugin Wiki page gives explanations on the configuration needed to setup the necessary commit hook on your Subversion server, for both Windows and Unix.

To put the workspace in the desired state before a build, the Subversion plugin offers various strategies:

• First, the most conservative one is to use a fresh new checkout for each build. This is the safer way to ensure the workspace reflects the exact state of a Subversion revision. The drawback is that this requires a complete checkout from the network on every build.
• The "Update" command can also be used to get Subversion, but only get the diff over the network from the Subversion server and get the workspace up more quickly. This may result in files from previous builds being present in the workspace.
• Update can be completed by a "Revert" pre-command to clean-up the workspace for any changes that the previous build may have made.
• The last strategy emulates a clean checkout by removing all unversioned files from the repository and then running the Update command.

Tips and Tricks
Selecting the adequate strategy depends on your build system. If you maintain a clean separation between source files and generated/compiled files, a simple update will be enough. But if you are used to changing source files during a build or to mixing source and generated files in the same directories, a more cautious strategy will be needed. The last two strategies are the most interesting ones to set up in an efficient CI, as they will reduce the network consumption, but still ensure a clean workspace to reflect the Subversion state for a revision.

With the improvements made in the upgrade from Subversion 1.4 to the recent 1.7, the Jenkins Subversion plugin can also use the SvnKit client API -- but with various levels of compatibility. Subversion externals, something that compares to symbolic links on Subversion repositories, has been improved in 1.6 to support externals to files. If your projects use this feature, you'll have to configure Jenkins to use this level of compatibility from the global configuration page.

The Jenkins Subversion plugin exposes the current state to the build as an environment variable, like $SVN_URL and $SVN_REVISION. You can use them in your build script to improve the metadata of the generated artifact. On a Java project you can, for example, include the Subversion URL and revision in your MANIFEST to easily retrieve the source code for a JAR.

Use on DEV@cloud
The Subversion plugin is, of course, available on CloudBees DEV@cloud and can be configured to access either SVN repositories hosted by CloudBees or your existing repository hosted on SourceForge, Google Code or your own infrastructure as long as it is available on the Internet using http(s).

Relevant Documentation
You can read more about the Subversion plugin on the Jenkins wiki https://wiki.jenkins-ci.org/display/JENKINS/Subversion+Plugin

You can read more about Subversion in general in the SVN e-book available at http://svnbook.red-bean.com/

Enjoy!

-- Nicolas de Loof, Senior Engineer

CloudBees
www.cloudbees.com
 

Follow CloudBees: