Using GitHub as a personal maven repository

Sometime you are in need for a maven repository accessible from the net which is under your control. Reasons might be:

  • a 3rd-party lib is not on Maven central or the desired version is missing
  • you built modules/libraries which will be included in your other projects

With the following steps you will be able to serve any artifact from a public GitHub repository by just added a few lines into your pom.xml. I personally wasted quite an amount of time on this topic so I guess I’ll save it here – for you and me.

Ready? Let’s start!

In our example we’ll use our GitHub repository to serve a file which is not available at Maven Central as the time of writing.

1. Creating the GitHub repository

Follow this link and create a new repository named mavenrepo.

You could as well choose a different name but then you will have to change every occurance in the following steps. Your call.

2. Creating the content for this repository

Change into the folder where the new repository will be lying on your disk. From here you will be able to push changes into your remote repository and thus update your artifacts.

1
2
3
4
5
6
7
8
9
10
11
12
13
~>cd dev
~/dev>mkdir mavenrepo
~/dev>cd mavenrepo
~/dev/mavenrepo>git init
~/dev/mavenrepo>git remote add origin git@github.com:YOURUSERNAME/mavenrepo.git
~/dev/mavenrepo>mkdir releases snapshots
#empty dirs can't be added to git
~/dev/mavenrepo>touch releases/README
~/dev/mavenrepo>touch snapshots/README
~/dev/mavenrepo>git add .
~/dev/mavenrepo>git commit -m "Initial setup"
#update the GitHub repo just for kicks
~/dev/mavenrepo>git push origin master

Cool, your local maven repository is waiting for it’s first artifact.

3. Creating the first artifact

Now you have to change to the location of your artifact-to-be.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
~/dev>cd ../../downloads/GoogleAnalyticsAndroid_1.3.1
~/downloads/GoogleAnalyticsAndroid_1.3.1>ls
libGoogleAnalytics.jar sample ReadMe.txt
#explanation below
~/downloads/GoogleAnalyticsAndroid_1.3.1>mvn deploy:deploy-file -DgroupId=com.google.android.apps -DartifactId=analytics -Dversion=1.3.1 -Dpackaging=jar -Dfile="libGoogleAnalytics.jar" -Durl=file:../../dev/mavenrepo/releases
 
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- maven-deploy-plugin:2.5:deploy-file (default-cli) @ standalone-pom ---
Uploading: file:../../dev/mavenrepo/releases/com/google/android/apps/analytics/1.3.1/analytics-1.3.1.jar
Uploaded: file:../../dev/mavenrepo/releases/com/google/android/apps/analytics/1.3.1/analytics-1.3.1.jar (43 KB at 751.5 KB/sec)
Uploading: file:../../dev/mavenrepo/releases/com/google/android/apps/analytics/1.3.1/analytics-1.3.1.pom
Uploaded: file:../../dev/mavenrepo/releases/com/google/android/apps/analytics/1.3.1/analytics-1.3.1.pom (400 B at 24.4 KB/sec)
Downloading: file:../../dev/mavenrepo/releases/com/google/android/apps/analytics/maven-metadata.xml
Uploading: file:../../dev/mavenrepo/releases/com/google/android/apps/analytics/maven-metadata.xml
Uploaded: file:../../dev/mavenrepo/releases/com/google/android/apps/analytics/maven-metadata.xml (307 B at 23.1 KB/sec)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.121s
[INFO] Finished at: Sun Sep 11 01:05:09 CEST 2011
[INFO] Final Memory: 3M/77M
[INFO] ------------------------------------------------------------------------

That’s (almost) it. Wait, what? No worries, I will explain the whole line for you so you can easily adjust it to your needs.

1
2
3
4
5
6
mvn deploy:deploy-file 
		#this specifies the artificat and will (=should) match with your dependency-declaration in pom.xml	
		-DgroupId=com.google.android.apps -DartifactId=analytics -Dversion=1.3.1 \ 
		-Dpackaging=jar \ #deploy as jar 
		-Dfile="libGoogleAnalytics.jar" \ #source file to deploy
		-Durl=file:../../dev/mavenrepo/releases #target folder to deploy

For 3rd-party-libraries which aren’t subject to change (i.e. no snapshots) use the releases folder for your own snapshots use – you guessed it – the snapshots folder.

Your maven repository is almost ready to serve.

4. Online artifacts!

Let’s change back to the maven repository. To make everything world accessible we have to commit and push the files.

1
2
3
4
5
6
7
~/downloads/GoogleAnalyticsAndroid_1.3.1>cd ../../dev/mavenrepo
# add everything which has changed or is new
~/dev/mavenrepo>git add .
# commit everything into the git-repo
~/dev/mavenrepo>git commit -m "Add Google Analytics library 1.3.1"
# push it to GitHub
~/dev/mavenrepo>git push origin master

So cool,eh? You can jump online to your GitHub repository to check if they’re there as expected. Aaalmost done.

5. Using your new maven repository

There are two ways to make maven aware of new repositories besides the pre-configured one. Either in ~/.m2/repositories/settings.xml which would be global for every repository but just for your user account. Or you can add the information into the pom.xml of your project. Since we want all developers for this project to easily use the new repository we will use the later.

Open your pom.xml and add the following lines for our example. Of course you have to edit the group-id, artifact and version according to your lib.

?Download pom.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelversion>4.0.0</modelversion>
    <!-- ... more project definition -->
 
    <dependencies>
 
        <dependency>
		<groupid>com.google.android.apps</groupid>
		<artifactid>analytics</artifactid>
		<version>1.3.1</version>
        </dependency>
        <!-- more dependecies... -->
    </dependencies>
 
    <!-- build config etc. ... -->
 
    	<repositories>
		<repository>
			<id>YOURUSERNAME-snapshots</id>
			<url>https://raw.github.com/YOURUSERNAME/mavenrepo/master/snapshots</url>
			<releases>
				<enabled>false</enabled>
				<updatepolicy>always</updatepolicy>
				<checksumpolicy>warn</checksumpolicy>
			</releases>
			<snapshots>
				<enabled>true</enabled>
				<updatepolicy>never</updatepolicy>
				<checksumpolicy>fail</checksumpolicy>
			</snapshots>
		</repository>
		<repository>
			<id>YOURUSERNAME-releases</id>
			<releases>
				<enabled>true</enabled>
				<updatepolicy>always</updatepolicy>
				<checksumpolicy>fail</checksumpolicy>
			</releases>
			<snapshots>
				<enabled>false</enabled>
				<updatepolicy>always</updatepolicy>
				<checksumpolicy>warn</checksumpolicy>
			</snapshots>
			<url>https://raw.github.com/YOURUSERNAME/mavenrepo/master/releases</url>
		</repository>
	</repositories>
</project>

That’s it!

6. Final: See it in action

Now we can start up maven to make use of the new configuration.

1
mvn clean package

If everything went well you should see “BUILD SUCCESS” and if you scroll up a bit you should see some Download-lines regarding your new repository. Maven will now try to load every new dependency from your GitHub-maven-repo so you can always decide if you want to host it yourself for some reason.

If you encountered errors along the way please let me know. This post is the result of several hours of trail and error and you should be fine following it. But of course it’s always possible you’ll run into problems.

Update:I noticed that I used the wrong group-id for my example. Normally it doesn’t hurt but it confuses everyone and so to be perfect added “.apps” to every occurance of this package-name.

About stevie

Born in the north of Germany, raised in Berlin and stayed there since. After graduating, studying applied computer science at the FHTW Berlin (now HTW Berlin), I started my own company with a former fellow student, providing high class application solutions for web and desktop for small and medium companies (see www.jnamic.com (english version to be finished) for more information). My personal favorite programming languages are PHP for the web and Java for everything else - although I must admit Java evolved very much in the past few years. I love to code and build new applications from the scratch, optimizing it through day and night till I am satisfied with it's performance. So follow my articles, share your thoughts and experience with me and have a good time browsing this blog!
This entry was posted in common and tagged , , , , , , . Bookmark the permalink.

One Response to Using GitHub as a personal maven repository

  1. Pingback: Hosting Maven Repository for third-party jars on Git (Bitbucket/Github) | Active Intelligence

Leave a Reply