Github offers out of the box some convenient plugins for interacting with Apache Maven. New Releases can be easily deployed and project websites on Github webspace can be promoted. Unfortunately, this plugin is neither interacting out of the box with the maven site:deploy command nor is it suitable for multi-module projects.

Background

I just invested some time to get my project websites online for jscsi.org.

Since jscsi.org is a multi-module project, the websites must respect this structure, especially when it comes to the deployment process. Unfortunately, the github-maven-plugin is not hooking into the deployment process directly, making a staging and deployment a little bit tricky.

Deploying Multi-Module Websites on Github

After struggling around with some (now unsupported and not over maven-central hosted) third-party plugins, I came up with a workflow including the original github-maven plugin and extended it with some Ant parts.

How it should be?

Maven projects often consists of multiple modules making a direct deploy bound to the “site”-phase not direct usable, just because of relative linking. Furthermore, a site:stage or site:deploy phase needs a suitable “site”-tag in the “distributionManagement”-section in the pom.

One possibility is to use a specialized gitsite-wagon (like https://github.com/khuxtable/wagon-gitsite), which is unfortunately neither updated nor accessible over central-repo. This makes a deploy of the own project on maven-central impossible.

How it is done?

The gab is filled by:

  • making a file deploy
  • copying the staged site to replace the former site generated for the root
  • deploy the root-site (which is actually the staged one) with the official github-maven plugin (also accessible over central-repo).

Enabling File Deploy

First, enable file-deploy for the root. Insert the following elements to the pom.xml

<distributionManagement>
   ...
   <site>
      <id>file</id>
      <url>file:${site.deploy.dir}</url>
   </site>
</distributionManagement>
<properties>
   ...
   <site.deploy.dir>/tmp/deploy</site.deploy.dir>
</properties>

The deploy to an absolute path is necessary: The pom containing the distributionManagement-Tag is the parent pom. If a relative shortcut like ${project.build.directory} is taken, the resolving takes place in a local manner (logically).

Afterwards, a site can be generated with

mvn site:site site:stage site:deploy

Two lines of Ant

Being deployed to ${site.deploy.dir}, the deployed content must be deployed to ROOT/target/site to get it to the place, where the github-plugin can deploy it from. Therefore, we need to adapt the parent pom a second time.

<build>
   <plugins>
   ....
      <plugin>
         <artifactId>maven-antrun-plugin</artifactId>
         <version>1.7</version>
         <configuration>
            <target>
               <delete dir="${project.build.directory}/site" />
               <copy todir="${project.build.directory}/site">
                  <fileset dir="${site.deploy.dir}" />
               </copy>
            </target>
         </configuration>
      </plugin>
   </plugins>
</build>

Since this script needs only to be executed on the parent-pom, an invocation takes place over

mvn antrun:run -N

Afterwards, the deployed site is accessible over “ROOT/target/site” ready to be deployed over the github-plugin.

Deploy

Insert the github site-plugin to the build-section of the pom (similar to the antrun-plugin):

<plugin>
   <groupId>com.github.github</groupId>
   <artifactId>site-maven-plugin</artifactId>
   <version>0.4</version>
   <configuration>
      <message>Building site for ${project.version}</message>
   </configuration>
</plugin>

Afterwards a deploy is executable over

mvn ghSite:site -N

Final notes

Some points must be noted:

  • The github-site as well as the antrun-plugin must be executed only on ROOT-level containing the parent pom(taking the “-N”).
  • Do only insert the modules in the “modules”-section where the page should be generated. All other modules can be covered over a separate profile.
  • In the modules, everything can be inherited except the “scm”-tag e.g.
<scm>
   <url>git@github.com:sebastiangraf/jSCSI.git</url>
   <connection>scm:git:git@github.com:sebastiangraf/jSCSI.git</connection>
   <developerConnection>scm:git:git@github.com:sebastiangraf/jSCSI.git</developerConnection>
</scm>

Otherwise, the github-plugin does not recognize the deploy and answers with

Listing downloads failed: Not Found (404)