Home » Java » Enterprise Java » Hosting a Maven repository on github (with sources and javadoc)

About Yifan Peng

Yifan Peng
Yifan is a senior CIS PhD student in University of Delaware. His main researches include relation extraction, sentence simplification, text mining and natural language processing. He does not consider himself of a Java geek, but all his projects are written in Java.

Hosting a Maven repository on github (with sources and javadoc)

How to make a small open sourced library available to other developers via maven? One way is to deploy it on Maven Central Repository. What I’d like to do is to deploy it to github, so I can modify it freely. This post will tell you how to do that.

The typical way I deploy artifacts to a github is to use mvn deploy. Here are steps:

  • Use site-maven-plugin to push the artifacts to github
  • Use maven-javadoc-plugin to push the javadoc
  • Use maven-source-plugin to push the source
  • Configure maven to use the remote mvn-repo as a maven repository

 

Configure maven-deploy-plugin

First, I add the following snippnet to tell maven to deploy artifacts to a temporary location inside my target directory:

<distributionManagement>
  <repository>
    <id>internal.repo</id>
    <name>Temporary Staging Repository</name>
    <url>file://${project.build.directory}/mvn-repo</url>
  </repository>
</distributionManagement>
<plugins>
  <plugin>
    <artifactId>maven-deploy-plugin</artifactId>
    <version>2.8.1</version>
    <configuration>
      <altDeploymentRepository>
      internal.repo::default::file://${project.build.directory}/mvn-repo
      </altDeploymentRepository>
    </configuration>
  </plugin>
</plugins>

Configure maven

Then I add my github.com authentication information to ~/.m2/settings.xml so that the github site-maven-plugin can push it to github:

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

or

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

Personally, I prefer the first way, because it is safer (without explicitly showing the password). To get the OAUTH2TOKEN of the github project, please go to settings --> Applications --> Genreate new token

Configure the site-maven-plugin

Configure the site-maven-plugin to upload from my temporary location to the mvn-repo branch on github:

<plugin>
  <groupId>com.github.github</groupId>
  <artifactId>site-maven-plugin</artifactId>
  <version>0.9</version>
  <configuration>
    <message>Maven artifacts for ${project.version}</message>
    <noJekyll>true</noJekyll>
    <outputDirectory>${project.build.directory}/mvn-repo
       </outputDirectory>
    <branch>refs/heads/mvn-repo</branch>
    <includes>
      <include>**/*</include>
    </includes>
    <repositoryName>pengyifan-commons</repositoryName>
    <repositoryOwner>yfpeng</repositoryOwner>
    <server>github</server>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>site</goal>
      </goals>
      <phase>deploy</phase>
    </execution>
  </executions>
</plugin>

When this post was writen, there was a bug in version 0.9 of site-maven-plugin. To work around, please git clone the 0.10-SNAPSHOT version and mvn install it mannually.

Configure maven-source-plugin

To add source code package into the mvn-repo, we need to configure the maven-source-plugin. Add the following code in pom.xml:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-source-plugin</artifactId>
  <version>2.3</version>
  <executions>
    <execution>
      <id>attach-sources</id>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Configure maven-javadoc-plugin

To add java doc package into the mvn-repo, we need to configure the maven-javadoc-plugin. Add the following code in pom.xml:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <executions>
    <execution>
      <id>attach-javadocs</id>
      <goals>
        <goal>jar</goal>
      </goals>
  </execution>
  </executions>
</plugin>

Now run mvn clean deploy. I saw maven-deploy-plugin “upload” the files to my local staging repository in the target directory, then site-maven-plugin commit those files and push them to the server.

To verfy all binaries are there, visit github in the browser, and select the mvn-repo branch.

Configure maven to use the remote mvn-repo as a maven repository

There’s one more step we should take, which is to configure any poms to know where our repository is. We can add the following snippet to any project’s pom.xml:

<repositories>
  <repository>
    <id>PROJECT-NAME-mvn-repo</id>
    <url>https://raw.github.com/USERNAME/PROJECT-NAME/mvn-repo/</url>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>
</repositories>
(0 rating, 0 votes)
You need to be a registered member to rate this.
4 Comments Views Tweet it!
Do you want to know how to develop your skillset to become a Java Rockstar?
Subscribe to our newsletter to start Rocking right now!
To get you started we give you our best selling eBooks for FREE!
1. JPA Mini Book
2. JVM Troubleshooting Guide
3. JUnit Tutorial for Unit Testing
4. Java Annotations Tutorial
5. Java Interview Questions
6. Spring Interview Questions
7. Android UI Design
and many more ....
I agree to the Terms and Privacy Policy

4
Leave a Reply

avatar
2 Comment threads
2 Thread replies
0 Followers
 
Most reacted comment
Hottest comment thread
3 Comment authors
TimurYifan PengJignesh Recent comment authors

This site uses Akismet to reduce spam. Learn how your comment data is processed.

  Subscribe  
newest oldest most voted
Notify of
Jignesh
Guest
Jignesh

I have hosted arctifact to my git repo, but now how use hosted jars as dependencies in another Maven project?

Yifan Peng
Guest
Yifan Peng

Did you follow the last section in this post? In your other projects, adding the xml code in the pom.xml should work.

Yifan Peng
Guest
Yifan Peng

Did you follow the last section in this post? In your other projects, adding the xml code in the pom.xml should work.

Timur
Guest
Timur

Hey Yifan. Shouldn’t I specify the groupId and artifactId of the jar somewhere?