Capture build information

This is an example demonstration of capturing information of the source code repository, system properties and environment variables into a text file during the build and packaging of your project. This example uses Maven and the associated plugins buildnumber-maven-plugin and maven-assembly-plugin.

Overview

In a continuous integration and deployment cycle it is useful to bundle associated metadata of the build into an easily viewable form such as a text file. This allows for understanding the foundation of the build and to trace steps backwards for troubleshooting potential bugs in the code or defects in the build process itself.

Using Maven, a couple of plugins and simple configuration this can be achieved easily.

There are a few files in the source tree:

• build_information.txt: The text file that will contain the information of the build. The file contains variables that will be filtered in after the build.
• assembly.xml: The descriptor file of the maven-assembly-plugin that orchestrates the build information filtering into the text file and the resulting artifact of the build.
• pom.xml: The maven project object model that declares the plugins, the configuration of them and its invocation phase and order during the build process.

Walkthrough of demonstration

build_inofrmation.txt

The build_information.txt file already contains variables to be filtered in during the build to demonstrate a working example:

revision : ${buildNumber}
branch : ${scmBranch}
build timestamp : ${timestamp}
built by : ${user.name}

The ${buildNumber} , ${scmBranch} and ${timestamp} are variables that are generated by the buildnumber-maven-plugin .The ${user.name} however is an Operating System environment variable which represents the current logged in user's account name.
You can add in as many Operating System environment variables or system properties into this file as you like and this build will filter those into the file. For example, I usually add in the Teamcity build job number into this file aswell when I use the build tool by adding this line:

Teamcity build tag id : ${build.number}

The Jenkins equivalent to this would be:

Jenkins build tag id : ${BUILD_NUMBER}

I have omitted these in this example to simplify the demonstration. If you would like to add these in and more variables of your continuous integration build tool, you can take a look at the available environment variables and system properties for both Teamcity and Jenkins

assembly.xml

The syntax of this descriptor file follows the standard convetions of the plugin as declared in its documentation. The part of the file that is significant for the build information:

		<fileSet>
			<directory>${basedir}/src/main/assembly</directory>
			<outputDirectory>/</outputDirectory>
			<includes>
				<include>build_information.txt</include>
			</includes>
			<filtered>true</filtered>
		</fileSet>

The fileset tag declaration instructs that the build_information.txt file in src/main/assembly should be placed at the root folder of the resulting artifact of the build.

Crucially the most important part in this is the inner tag:

<filtered>true</filtered>

This is the configuration switch that allows for all declared variables in the file to be filtered by property substitution with the relevant system property or environment variable.

Running the demonstration

Run the clean package maven goals. on the command line this would be mvn clean package at the root folder of the project.

There will be a zip file produced called capture-build-information-1.0.0-SNAPSHOT.zip in the target folder. After opening the zip file you will see the build_information.txt file that contains the filtered values.
Here is an example build_information.txt file after the build:

revision : 5299269031c168408532e3326997135f784e663a
branch : master
build timestamp : 2017-01-07 15:11:10
built by : hakan