Git Wagon Provider
This is a Wagon Provider for Git that works with GitHub Pages and works with multi-module projects.
Registering the plugin
The plugin can be registered as a dependency in the
extension for the project. It is recommended that the dependency
approach is used to prevent polluting the maven namespace.
<plugin> <artifactId>maven-site-plugin</artifactId> <version>3.3</version> <dependencies> <dependency> <groupId>net.trajano.wagon</groupId> <artifactId>wagon-git</artifactId> <version>2.0.0</version> </dependency> </dependencies> </plugin>
<distributionManagement>/<site> needs to be set as
<distributionManagement> <site> <id>gh-pages</id> <name>Trajano GitHub Pages</name> <url>github:http://trajano.github.io/trajano/</url> <!-- <url>git:ssh://firstname.lastname@example.org/trajano/trajano.git?gh-pages#</url> --> </site> </distributionManagement>
<name> can be any value.
<id> to represent the authentication details in
settings.xml. At a minimum,
settings.xml file must contain a
<server> with this
<id> and a valid
<username> element (
git if using ssh, or your github username if using
http). If you use passwordless-ssh with no password on the key file, then no
password is necessary.
<server> <id>gh-pages</id> <username>git</username> <!-- different method for http authentication --> <!-- <username>trajano</username> --> <!-- supply a password for your ssh keyfile or your http account --> <!-- <password>trajano's_pass</password> --> </server>
For generic git repositories, the
<url> must start with
git: and end
#. The branch name must also be specified between the
# at the end is required to prevent additional characters
that will be appended by Maven to be considered as part of the original URL.
Multi-module and project.artifactId
Do not use the form in multi-module projects
because the sub modules will use the
artifactId of the current module and
not make it part of the parent which site would be expecting. This is not
just a limitation of this plugin but is a limitation of the Maven site plugin
itself. Instead explicity set it on your multi-module project POM e.g.
Protected private keys
If you are using a passphrase to protect your private key, then in
settings.xml, then should be a
<server> definition with the
corresponding to the
<distributionManagement><site><id> and with a
<passphrase> element but without the
<user>. For example:
<server> <id>gh-pages</id> <passphrase>privatekeypassphrase</passphrase> </server>
If you're not protecting your private key, then no additional changes are
Module and parent references
At the moment if you are referencing the parent project or modules, using the
following in the
<menu ref="parent" inherit="top" /> <menu ref="modules" inherit="top" />
The problem is a broken implementation of the path logic done by the doxia-integation-tools from Maven. A bug and patch has been provided by Archimedes Trajano called MSITE-709 to resolve the issue. For those that need the fix immediately, an alternative doxia-integration-tools has been made available and can be added as a dependency to the site plugin or as a build extension.
<plugin> <artifactId>maven-site-plugin</artifactId> <dependencies> <dependency> <groupId>net.trajano.maven.doxia</groupId> <artifactId>doxia-integration-tools</artifactId> <version>2.0.0</version> </dependency> </dependencies> </plugin>
Projects such as mybatis4 use a non relative parent. This causes a conflict
when trying to release when both the non-relative parent and submodule uses
github: style resulting in NullPointerException similar to the following.
[INFO] Pushing C:\mybatis\ehcache-cache\target\site [INFO] >>> to github:ssh://mybatis.github.io/parent/../ehcache-cache
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.4:deploy (default-cli) on project mybatis-ehcache: Execution default-cli of goal org.apache.maven.plugins:maven-site-plugin:3.4:deploy failed. NullPointerException
A work around for this issue is to use the
github: style in the non-relative
parent and to use the generic git style for submodules.