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.