Github Pages with Maven

Github recently introduced their pages feature, for serving static content. This sounds like an ideal match for a maven , so I thought I’d give it a go. I managed to get up and running in fairly short order, but I’m not totally happy with the end result. And that’s not just the fault of the default maven site.

First things first. We need to set up the gh-pages branch as devoid of content. I nicked most of this from drnic’s sake-tasks, even though the instructions are also on

git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx
echo "

Coming soon!

" >index.html git add index.html git commit -a -m 'Initial page' git push origin gh-pages

Soon, you should be able to see the “Coming soon!” message on

Now that’s there, we need to set it up so that maven can deploy the site to it. First, let’s add the branch as a submodule.

repo=`git config remote.origin.url`
git submodule add -b gh-pages $repo site

That should create a directory “site” which contains the index.html you committed a moment ago. Now you have to ask Maven to deploy the site there. Add this to your POM.


Now you can say mvn site-deploy and it will fill up the site directory with lots of lovely HTML. Then you have to commit it (separately, since it’s a submodule) and push it back to github.

  mvn site-deploy
    cd site
    git add .
    git commit -a -m 'Generate site.'
    git push origin gh-pages

And shortly thereafter it shows up on the web site. Magic.

I like this a lot in principal. But I have a few issues with it as well. Mostly, this is down to git submodules being quite a blunt instrument:

  • They don’t auto-update when there’s a new commit in the submodule — they point at a fixed commit. You have to ask for it to be updated.
  • On top of that, you can’t point the submodule at a branch. It’s always pointing at a specific commit.
  • The submodule location is recorded in .gitmodules. The main issue I have with this is I can’t find a way to say “my current repository”. Why is this a problem? Well, if somebody forks the codebase (and they will, this is git) then they want their site to point at their gh-pages branch, not mine.
  • The submodule location is my private push URL, not the public one. Which is all well and good, but when somebody checks out the project, they’re going to have an error when they try to check it out. As I found out when setting up the build in hudson.
  • When somebody else checks out the repository they have an extra step to go through to fetch the submodule contents (git submodule init git submodule update).

I think that next time I try this, I’ll skip submodules and just checkout a second copy of the repo in ../project-site.

I still think it’s the right way to go. Not just for the site, but you can also use github pages to serve up a maven repository in a very similar fashion. Github and maven do seem to go together rather well.

4 replies on “Github Pages with Maven”

What did you end up doing with this in the end? I’d like to do the same thing you are, but the things that stuff it up for people downstream makes me very nervous.

@Lewisham: I haven’t progressed any further with it. My experience with the above is that I should be avoiding submodules for the job though… I get the feeling that some scripting is probably necessary. Maybe a little helper maven plugin?

I am still using github pages, but for a different purpose.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s