Publishing a Maven Site to GitHub Pages with Travis-CI
19 Dec 2015
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.
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
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.
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:
The one thing not covered in the Travis-CI docs page is that you can have multiple encrypted environment variables like so:
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.