Continuous Integration for GitHub Java Projects

This post discusses how to setup a Java GitHub project with code coverage and continuous integration that is run automatically on each commit.

Working on the WordBrain Solver I wrote about last month, I thought it’d be interesting to set the project up to do this, and set up a few extra reporting tasks. This project manages:

  • Build. Managed by maven.
  • Code coverage. Instrumented by Jacoco.
  • Reporting. FindBugs and PMD reports.
  • Continuous Integration. Updates automatically pushed to Travis CI.
  • Code coverage reports. Published on Coveralls.

The result is a set of tags displaying the state of the project on GitHub:

Result Badges

Maven

The majority of the setup for all of these tools is in the project’s pom.xml file.

This is broken into three key sections:

  • Dependencies, which includes each of the libraries used in the project. Libraries that are only used in testing are given the test scope, meaning they are unit included in the release of the project.
  • Build, which describes where the code is located and how to build the code. This includes the plugins used to run unit tests and instrument code coverage.
  • Reporting, which includes plugins that are used to generate analysis or reports of the code. This includes the generation of JavaDoc, and plugins such as PMD and FindBugs.

Instrumenting Code Coverage

Code coverage is included in the build section of the pom. The code coverage tool i’m using, Jacoco, is executed in two phases:

The pre-unit-test phase attaches the jacoco agent to the JVM used to run the unit tests. In this execution, surefireArgLine is used to add the agent to the surefire test runner as an extra JVM parameter here.

The post-unit-test phase is run after the unit tests have completed, analyzing the jacoco output to produce a nice HTML report.
The jacoco agent is attached to the unit tests (run with surefire), by adding to the surefire argline here.

To generate code coverage results (created by default in target/jacoco-ut), run the test command:

Reporting: FindBugs and PMD

Published Results

While the code coverage tools form part of the maven build process, the maven reporting process includes plugins such as FindBugs and PMD.

In this pom, I added reporting for: JDepend, FindBugs, PMD, JavaDoc, and Surefire.

Adding them is as simple as adding the maven dependency, and running them is as simple as:

Continuous Integration: Travis CI

Travis CI Page

Travis CI is free for open source projects, so it’s a great tool to use if you have a project like this one. All it requires is a yml file specifying what the server should run (and signing up to the website):

If this file is set up correctly, you shouldn’t need anything else in your project. Travis automatically builds every time you push to your main branch.

Coverage Reporting: Coveralls

Coveralls Site

Coveralls automatically accepts coverage reports from Travis CI and displays them in nice interface.

As with Travis, it’s free for open source projects, and as with Travis, it doesn’t require much configuration.

Once you’re signed up, the only addition to the project is a maven build plugin:

Pushing updates from your local machine or another build server requires you to enter an authentication token here, but if you’re using Travis you don’t need any additional setup. The following line in the travis.yml file creates and sends the coverage report with no additional configuration:

Results

Result Badges

The result of this configuration is a pair of badges showing the current state of the build and the code coverage.

More importantly, it sets the project up for future work with a great set of tools for monitoring the state of development.

Angus Macdonald

Angus works in New York City for Google. He has a PhD in Computer Science from the University of St Andrews.

Latest posts by Angus Macdonald (see all)

2 thoughts on “Continuous Integration for GitHub Java Projects

  1. Absolutely wonderful blog post. Simple, to the point, shows exactly where stuff is included. Helped me fix a non-working JaCoCo install and add on coveralls (which I’ve wanted for months!)

    One tiny error: you have “+” at the beginning of your travis.yml lines, which is ignored. The correct syntax is a “-” sign (as in your linked file)

Leave a Reply

Your email address will not be published. Required fields are marked *