Putting a maven version label on a bamboo build

This took a couple of hours to do the other day, so perhaps someone else out there might find this useful.

Bamboo‘s great[*], it allows you to continuously integrate your source trees so that you’ve got a reasonably good chance of knowing that your code builds and tests correctly.

Maven‘s great[**], it allows you to package your source code into libraries and maintain the dependencies between them

So anyway, bamboo’s got its build IDs, and maven’s got its version numbers. It would be nice if you could merge the two of them.

What I do is to label builds in bamboo with the version number of the project being built, which looks a bit like this:

This is surprisingly more difficult to do than it would at first appear.

To get this to work, I ended up:

• Writing a maven plugin that is called from within the Bamboo build process
• This plugin invokes the Bamboo REST API to label the build in which it is currently running
• Configuring the settings.xml on the Bamboo server to contain the Bamboo connection settings used by the plugin, and to allow the plugin to be referred to by its short name
• Added the maven goal provided by this plugin to every maven build in Bamboo

The Maven plugin

The source code for the plugin looks like this:

[rn-sourcecode lang=”java” src=”vmaint-maven-plugin/src/main/java/com/randomnoun/maven/plugin/vmaint/LabelBambooMojo.java” errors=”true”]

The references to ‘vmaint’ here refer to my internal virtual machine maintenance scripts, which I intend to publish on the net at some stage. You can track the progress (or lack thereof) of this project here.

Anyway, rather than compiling the code above, you can download the plugin JARs and its sources here if you like [Update: although this now shouldn’t be necessary as the artifact is in the maven central repository]:

• The JAR: vmaint-maven-plugin-1.1.0.jar
• The JAR sources: vmaint-maven-plugin-1.1.0-sources.jar

Install it into your repository manager (if you have one) with this command-line:

C:> c:\java\prog\apache-maven-3.0.4\bin\mvn deploy:deploy-file 
  -Durl=http://nexus.dev.randomnoun:8082/nexus/content/repositories/releases/ 
  -DrepositoryId=releases -Dfile=vmaint-maven-plugin-1.1.0.jar 
  -DgroupId=com.randomnoun.maven.plugins -DartifactId=vmaint-maven-plugin 
  -Dversion=1.1.0 -Dpackaging=jar -DgeneratePom=false

C:> c:\java\prog\apache-maven-3.0.4\bin\mvn deploy:deploy-file 
  -Durl=http://nexus.dev.randomnoun:8082/nexus/content/repositories/releases/ 
  -DrepositoryId=releases -Dfile=vmaint-maven-plugin-1.0.0-sources.jar 
  -DgroupId=com.randomnoun.maven.plugins -DartifactId=vmaint-maven-plugin 
  -Dversion=1.1.0 -Dpackaging=java-source -DgeneratePom=false

replacing the path to mvn and the repository URL as necessary.

Configuring settings.xml

Two things need to be specified in the settings.xml on the bamboo server in order to use this plugin:

• The connection settings to bamboo, including the username/password credentials used to authorise the labelling of the build using the REST API. This user needs to be configured within Bamboo and have write access to the build in which it runs
• A plugin prefix declaration. This isn’t absolutely necessary, but it does let you run things like mvn vmaint:label-bamboo instead of mvn com.randomnoun.maven.plugins:vmaint-maven-plugin:label-bamboo:1.0.0

You could, if you like, set the bamboo connection settings within your project’s pom.xml file but this could get repetitive over a large number of projects, and would expose the username/password in a public source-controlled file, which may not be something that you want.

Instead, find the settings.xml file that your Bamboo instance is using (on a Bamboo instance running as a Windows service, this is under C:\.m2\settings.xml ), and update these sections:

<settings>

  <pluginGroups>
    <!-- this plugin group allows us to run 
      mvn vmaint:label-bamboo
    rather than 
      mvn com.randomnoun.maven.plugins:vmaint-maven-plugin:label-bamboo
    -->         
    <pluginGroup>com.randomnoun.maven.plugins</pluginGroup>
  </pluginGroups>

  <!-- mirrors section here -->

  <profiles>
    <profile>
      <id>default</id>
      
      <!-- reposities section here -->
      <!-- plugin repositories section here -->
      <properties>
        <!-- we use the dot-separated maven property naming convention here -->
        <bamboo.rest.url>http://my-bamboo-server/bamboo/rest</bamboo.rest.url>  
        <bamboo.rest.username>my-bamboo-username</bamboo.rest.username>  
        <bamboo.rest.password>my-bamboo-password</bamboo.rest.password>  
      </properties>
    </profile>
    
    <!-- repeat properties section in any other profiles -->
    
  </profiles>
  
  <activeProfiles>
    <activeProfile>default</activeProfile>
  </activeProfiles>
  
  <!-- servers section here -->
  
</settings>

Configuring the tasks in Bamboo

So each project in bamboo has plans, and each plan has stages, and each stage has jobs, and each job has tasks. If you’re anything like me, then there’s only one stage with one job with one task, which is something like ‘Maven build’.

What you want in your Maven bamboo task is the following goal settings:

-B  vmaint:label-bamboo clean deploy 
"-DbambooBuildKey=${bamboo.buildKey}" 
"-DbambooBuildNumber=${bamboo.buildNumber}" 
"-DbambooBuildPlanName=${bamboo.buildPlanName}" 

The -B denotes a batch (non-interactive) build; this prevents maven from displaying progress percentages when uploading files, which can otherwise fill the build log files.

I sometimes put -U here as well to force maven to update any referenced snapshot artifacts from the artifact repository, but don’t have it on this build for some reason.

The vmaint:label-bamboo goal triggers the bamboo label, and the clean and deploy goals perform a standard maven clean, compile, build, test, install and deploy cycle.

The other parameters pass bamboo build information through to the maven plugin using the bamboo variable substitution mechanism.

Anyway; after possibly restarting bamboo to pick up the new settings.xml settings, try running a build and, with luck, you’ll have your maven version number labelled against your build ! Exciting !

[*] – except for its rubbish data model

[**] – except for its speed, choice of XML representation, nonstandard terminology, and various other idiosyncracies and inconsistencies, which I’m sure I’ll complain about at a later juncture.