Publish Maven Site Documentation automatically to the GitHub Pages

Maven site is a great tool as well as GitHub. The coolest thing about those tools is that they play together very well. Only a little Maven configuration is needed. But let me explain shortly what both tools do.

Maven Site: generates automatically a nice documentation website for your Maven project. Many Apache projects uses this generated site as their main website. So probably you have already seen such generated websites. An nice example is the my (parent) POM project or the maven-site-plugin. Mainly the documentation consists of three parts:

• Project information like dependencies, license, source repository and so on. 
• Project reports like unit tests reports, static code analysis reports, JavaDocs and so on. 
• The documentation written by the developers. With an additional Maven Plugin it's possible to write the documentation with Markdown.

GitHub Pages: GitHub doesn't only provide a GIT repository but also can be used as webhost for static website. Which is ideal for a project website. The GitHub Pages concept is very cool. It's just a branch, called gh-pages, in you project repository. All the files that are pushed into this branch will be served from GitHub`s webserver. An nice example is the documentation for my (parent) POM project.
Before you start with the Maven configuration you should read Creating Project Pages manually for a better understanding.

Before we can start with the GitHub Pages integration into Maven we firstly need to correctly build the website. For multi module projects it's necessary to deploy (locally is sufficient) the website first. Otherwise the references between modules won't work. To do so you just need to configure the distribution management like this:

<distributionManagement>
<site>
<id>site-docs</id>
<url>file://${env.HOME}/sitedocs/pom-project</url>
</site>
</distributionManagement>

How to fully configure the generation of the Maven Site is too much for this blog post. Look at the POM for some good basic configuration or just us it as parent POM for your project. The minimum of configuration is:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.4</version>
            <executions>
                <!-- used for multiproject builds -->
                <execution>
                    <id>attach-descriptor</id>
                    <goals>
                        <goal>attach-descriptor</goal>
                    </goals>
                </execution>
            </executions>
            <dependencies>
                <!-- To use the Markdown format -->
                <dependency>
                    <groupId>org.apache.maven.doxia</groupId>
                    <artifactId>doxia-module-markdown</artifactId>
                    <version>1.6</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

<reporting>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-project-info-reports-plugin</artifactId>
            <version>2.7</version>
            <configuration>
                <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
            </configuration>
            <reportSets>
                <reportSet>
                    <reports>
                        <report>index</report>
                        <!--<report>cim</report>-->
                        <report>dependencies</report>
                        <!--<report>dependency-convergence</report>-->
                        <report>dependency-info</report>
                        <report>dependency-management</report>
                        <!--<report>distribution-management</report>-->
                        <!--<report>issue-tracking</report>-->
                        <report>license</report>
                        <!--<report>mailing-list</report>-->
                        <report>modules</report>
                        <report>plugin-management</report>
                        <report>project-team</report>
                        <report>scm</report>
                        <report>summary</report>
                    </reports>
                </reportSet>
            </reportSets>
        </plugin>
    </plugins>
</reporting>

To build the Maven Site just use: mvn clean site site:deploy

The integration into the GitHub pages is very easy and looks like this:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-scm-publish-plugin</artifactId>
            <version>1.1</version>
            <inherited>true</inherited>
            <configuration>
                <checkoutDirectory>${project.basedir}/github.com</checkoutDirectory>
                <checkinComment>publishing site documentation</checkinComment>
                <content>${env.HOME}/sitedocs/pom-project</content>
                <pubScmUrl>scm:git:https://github.com/rseiler/pom-project.git</pubScmUrl>
                <scmBranch>gh-pages</scmBranch>
            </configuration>
        </plugin>
    </plugins>
</build>

Additional you need to configure your username and password in the .m2/settings.xml. It should look like this:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>github.com</id>
      <username>github-username</username>
      <password>github-password</password>
    </server>
  </servers>
</settings>

If everything is done just type: 

mvn clean site site:deploy scm-publish:publish-scm -Dscmpublish.dryRun=true

The scmpublish.dryRun flag prevents the plugin to commit anything and just outputs what changes it would commit. Check it and if everything works than rerun the command without this flag: 

mvn clean site site:deploy scm-publish:publish-scm

That's it! It's Very simple :)