INTRO

GitHub provides an incredible feature that allows us to easily push Maven generated site to our project’s GitHub repository.

Here’s how to do it…

STEP 1: Define GitHub credential

Go to ~/.m2/settings.xml and add your GitHub username and password:-

<settings ...>
	<servers>
		<server>
			<id>github</id>
			<username>USERNAME</username>
			<password>PASSWORD</password>
		</server>
	</servers>
</settings>

STEP 2: Define GitHub’s site-maven-plugin

GitHub provides its own site-maven-plugin that can be used to deploy a Maven generated site to a gh-pages branch so that it can be served statically as a GitHub Project Page.

In pom.xml, add the following plugin configuration:-

<project ...>
    ...
    <build>
        <plugins>
            ...
            <plugin>
                <groupId>com.github.github</groupId>
                <artifactId>site-maven-plugin</artifactId>
                <version>0.11</version>
                <configuration>
                    <message>Creating site for ${project.version}</message>
                    <server>github</server>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>site</goal>
                        </goals>
                        <phase>site</phase>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
    ...
</project>

STEP 3: Define project URL

In pom.xml, define <url> tag that points to the project’s GitHub repository.

<project ...>
    <groupId>...</groupId>
    <artifactId>...</artifactId>
    <version>...</version>
    <url>https://github.com/USERNAME/PROJECT-NAME</url>
	...
</project>

If this is not defined, Maven will throw the following error when executing mvn clean site:-

Failed to execute goal com.github.github:site-maven-plugin:0.11:site 
(default) on project PROJECT-NAME: No GitHub repository (owner and 
name) configured -> [Help 1]

STEP 4: Generate Maven site and push to GitHub

Finally, run the following command: mvn clean site.

The generated site can be viewed from https://USERNAME.github.io/PROJECT-NAME/ .

That’s it…. very simple.