Hosting a maven repository on Github: site-maven-plugin

This article provides a step by step guide on publishing a maven project from GitHub using site-maven-plugin.

Prerequisites

• Project repository on Github
• Java and Maven
• Familiarity with Maven configuration

Create a repository for your maven project on Github if you don't have one already and push your maven project. This method will use the site-maven-plugin to push the artifacts to Github.

This approach does not cause conflict with gh-pages and other branch as the artifacts is pushed to the mvn-repo branch of your repository, every time the mvn deploy command is executed the new build artifact will be published.

First, the maven artifact has to be deployed to a temporary location in the build/target directory. Add the following repository to the project pom.xml:

<distributionManagement>
    <repository>
        <id>internal.repo</id>
        <name>Temporary Staging Repository</name>
        <url>file://${project.build.directory}/mvn-repo</url>
    </repository>
</distributionManagement>

Add the maven-deploy-plugin configuration to your pom.xml:

<plugin>
    <artifactId>maven-deploy-plugin</artifactId>
    <version>2.8.2</version>
    <configuration>
        <altDeploymentRepository>internal.repo::default::file://${project.build.directory}/mvn-repo</altDeploymentRepository>
    </configuration>
</plugin> 

After adding the above repository and plugin to your pom.xml execute mvn deploy, the maven repository will be deployed to the directory target/mvn-repo/. The next step is to deploy to github mvn-repo branch.

Configure github authentication information in ~/.m2/settings.xml to enable site-maven-plugin push to github. if the file settings.xml does not exist it should be created.

There are several ways to authenticate github, add one of the following configuration to your ~/.m2/settings.xml.

using your github username and password:

<settings>
  <servers>
    <server>
      <id>github</id>
      <username>GitHubLogin</username>
      <password>GitHubPassw0rd</password>
    </server>
  </servers>
</settings>

using OAUTH2TOKEN:

<settings>
  <servers>
    <server>
      <id>github</id>
      <password>OAUTH2TOKEN</password>
    </server>
  </servers>
</settings>

Then add the following to your pom.xml:

<properties>
  <github.global.server>github</github.global.server>
</properties>

The last step is to configure site-maven-plugin to push your local staging repo target/mvn-repo/ to your remote mvn-repo branch.

<plugin>
    <groupId>com.github.github</groupId>
    <artifactId>site-maven-plugin</artifactId>
    <version>0.11</version>
    <configuration>
        <message>Maven artifacts for ${project.version}</message> <!-- git commit message -->
        <noJekyll>true</noJekyll>  <!-- disable webpage processing -->
        <outputDirectory>${project.build.directory}/mvn-repo</outputDirectory> <!-- matches distribution management repository url above -->
        <branch>refs/heads/mvn-repo</branch> <!-- remote branch name -->
        <includes><include>**/*</include></includes>
        <repositoryName>YOUR-REPOSITORY-NAME</repositoryName> <!-- github repo name -->
        <repositoryOwner>THE-REPOSITORY-OWNER</repositoryOwner> <!-- organization or user name  -->
    </configuration>
    <executions> <!-- run site-maven-plugin's 'site' target as part of the build's normal 'deploy' phase -->
      <execution>
        <goals>
          <goal>site</goal>
        </goals>
        <phase>deploy</phase>
      </execution>
    </executions>
</plugin>

repositoryOwner value is is the parent name of the repo, if the repo is owned by a github organization the value will be the organization name and if the repo is owned by a user the value will be the username e.g. for the repo keyvaluedb/key-value-db-java, repositoryName value will be key-value-db-java and repositoryOwner value will be keyvaluedb.

Execute mvn deploy to upload your artifact to github. The mvn-repo branch will be created if it does not exist.

Visit github.com in your browser, select the mvn-repo branch, and verify that all your binaries are uploaded.

Hooray. Your maven project is now available to be used in other projects.

Every time you run mvn clean deploy command on your project, the latest artifacts will be uploaded to github.

Other maven project using your project can be configured to pull your artifact from github. Add the following snippet to the pom.xml files that depend on your project.

<dependency>
    <groupId>YOUR.PROJECT.GROUPID</groupId>
    <artifactId>ARTIFACT-ID</artifactId>
    <version>VERSION</version>
</dependency>

<repository>
    <id>ARTIFACT-ID</id>
    <url>https://raw.github.com/REPOSITORYOWNER/REPOSITORY-NAME/mvn-repo/</url>
</repository>

After adding the properties to the pom.xml the project will automatically download your maven repository jars from github.