Making Noises with Hudson/Jenkins

This is an extract from the upcoming book 'Continuous Integration with Hudson', an open source book on Hudson/Jenkins freely available online, soon to be published in paper form by O'Reilly.

While it is important to get your build server building your software, it is even more important to get your build server to let people know when it can't do so. A crucial part of the value proposition of any Continuous Integration environment is to improve the flow of information about the health of your project, be it failing unit tests or regressions in the integration test suite, or other quality related issues such as a drop in code coverage or code quality metrics. In all cases, a CI server must let the right people know about any new issues, and it must be able to do so fast. This is what we call Notification.

If you have your Jenkins/Hudson instance running on a machine that is physically located in proximity to the development team, you may also want to add sounds into the mix of notification strategies. This can be an effective strategy for small co-located teams, though it becomes trickier if the build server is set up on a virtual machine or elsewhere in the building.

There are two ways to integrate audio feedback into your build process in Hudson: the Hudson Sounds plugin and the Hudson Speaks plugin. Both can be installed via the 'Plugin Manager' page in the usual manner.

The Hudson Sounds plugin is the most flexible of the two. It allows you to build a detailed notification strategy based on the latest build result and also (optionally) on the previous build result as well. For example, you can configure Hudson to play one sound the first time a build fails, a different sound if the build fails a second time, and yet another sound when the build is fixed.

To set this up, you need to tick the 'Hudson Sounds' checkbox in the Post-build actions section of your build job configuration page. You can add as many sound configuration rules as you like. Adding a rule is simple enough. First, you need to choose which build result will trigger the sound. You also need to specify the previous build results for which this rule is applicable: Not Build (NB), Aborted (Ab), Failed (Fa), Unsuccessful (Un) or Successful (Su).

The Hudson Sounds plugin proposes a large list of pre-defined sounds, which usually offer plenty of choice for even the most discerning build administrator, but you can add your own to the list if you really want to. Sounds are stored as a zip or jar file containing sound files in a flat directory structure (i.e. no sub-directories). The list of sounds proposed by the plugin is simply the list of filenames, minus the extensions. The plugin supports AIFF, AU and WAV files.

In the System Configuration page, you can give Hudson a new sound archive file, using the http:// notation if your sound archive file is available on a local web server, or the file:// notation if it is available locally. Once you have saved the configuration, you can test the sounds in your sound archive via the 'Test Sound' button in the 'Advanced' section.

The Hudson Sounds plugin is an excellent choice if you want to complement your more conventional notification techniques. Short, recognizable sounds are a great way to grab a developer's attention and let the team know that something needs fixing. They will then be a bit more receptive when the more detailed notifications follow.

Another option is the Hudson Speaks plugin. With this plugin, you can get Hudson to broadcast a customized announcement (in a very robotic voice) when your build fails. You can configure the exact message using Jelly. Jelly is an XML-based scripting language used widely in the lower levels of Hudson.

Jelly is a flexible, if somewhat cumbersome, scripting language. The advantage of this approach lies in it's precision: since you can use Hudson variables in the Jelly script, you can get Hudson to say just about anything you want about the state of the build. Here is a simple example:

<j:choose>
  <j:when test="${build.result!='SUCCESS'}">
    Your attention please. Project ${build.project.name} has failed
    <j:if test="${build.project.lastBuild.result!='SUCCESS'}"> again</j:if>
  </j:when>
  <j:otherwise><!-- Say nothing --></j:otherwise>
</j:choose>

If you leave this field blank, the plugin will use a default template that you can configure in the System Configuration page. In fact, it is usually a good idea to do this, and only to use a project-specific script if you really need to.

The disadvantage is that the robotic voice can make it a little hard to understand. For this reason, it is a good idea to start your announcement with a generic phrase such as "Your attention please", or to combine it with the Hudson Sounds plugin, so that you have developers' attention before the actual message is broadcast. Using hyphens in your project names (e.g. 'game-of-life' rather then 'gameoflife') will also help the plugin know how to pronounce your project names.

Both these approaches are useful for small teams, but can be limited for larger ones, when the server is not physically located in close proximity to the development team. Future versions may support playing sounds on a separate machine, but at the time of writing this feature was not available.

From http://weblogs.java.net/blog/johnsmart/archive/2011/01/31/making-noices-hudsonjenkins