Michael Lanyon's Blog Notes and thoughts from LanyonM

Publishing a Maven Site to GitHub Pages with Travis-CI

• • • • • •

Comments

Part of continuous delivery is continuously delivering documentation along with the software. I’d go so far as to argue that it’s part of the software. In the past I’ve had to remember to run mvn site periodically to ensure that the latest javadoc and dependency updates report get created, but there’s gotta be a better way!

The key to this integration is having Travis authenticate back to GitHub to publish to gh-pages in a secure way. The default suggestion for publishing with GitHub’s site-maven-plugin is to add your username & password or an oauth token to ~/.m2/settings.xml. This won’t work for Travis-CI and would leak the oauth token.

POM Configuration

The site-maven-plugin configuration is exactly the same as GitHub’s example, but that’s to be expected. The important configuration is to allow the oauth token to be read from an environment variable (excerpt from pom.xml):

<project>
    <properties>
        <github.global.server>github</github.global.server>
        <github.global.oauth2Token>${env.GITHUB_OAUTH_TOKEN}</github.global.oauth2Token>
    </properties>
</project>

To be able to run mvn site locally you’ll need to run export GITHUB_OAUTH_TOKEN="your-github-personal-access-token" or add that line to your dotfiles. To create the token follow these instructions. The token I created has repo and user:email access.

Travis-CI Configuration

Encrypted Environment Variable

Getting your GitHub token into the Travis-CI environment var is very well documented. Here’s a handy copy/paste of the command you’ll want to run to encrypt your environment variable:

travis encrypt GITHUB_OAUTH_TOKEN="your-github-personal-access-token" --add env.global

The one thing not covered in the Travis-CI docs page is that you can have multiple encrypted environment variables like so:

env:
  global:
    secure: bigEncryptedString/One
    secure: bigEncryptedString/Two

Build Timeout

Another thing to consider is that the site-maven-plugin can take quite a while to prepare and upload the site html to your gh-pages branch. By default this process does not generate log statements and Travis-CI may time-out. You can either have Travis extend the timeout or enable debug logging for Maven: mvn site -X. I chose the second option because I didn’t want some other issue to cause long build times. The .travis.yml has the full details.

Summary

You can see this working in my Spring playground repository which publishes here. Please let me know if you find this helpful or have suggestions for improvements.