Hosting a maven repository on Github: site-maven-plugin
Tags: github, java, maven, android
Published: 2020-01-27 16:36:04


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](https://github.com/github/maven-plugins) 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:

```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:

```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: 

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

using [OAUTH2TOKEN](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line):

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

Then add the following to your **pom.xml**: 

```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. 

```xml
<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](https://github.com/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.

![Alt Text](https://thepracticaldev.s3.amazonaws.com/i/q7c0lggi54x51do4o4p6.png)

**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. 

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

```xml
<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.