Skip to content
November 8, 2011 / marrowboy

How to host a maven repo on github

If you’re anything like me, you probably make little throwaway projects in order to learn something. Sometimes they turn out quite cool but mostly they don’t. Doesn’t matter, but the ones that are nice enough to share present you with a dilemma – you want to share what you made but they’re probably not worth the effort of putting in a public repo like Sonatype with all the ceremony entailed. Here I’ll walk through the process of setting up a repo on github which people can add to their maven builds to pull your code right in. I won’t go into details on maven or how its dependency management system works – you can read about that elsewhere. This method will also work for the other build tools which know about the maven repo layout like sbt, leiningen, and others.

1. Make a github project

Just create a normal repo on github. I called mine mjg-repo and my username is mjg123, so the repo home is at https://github.com/mjg123/mjg-repo. Follow the instructions in your new repo to put a README file in your lovely new repo.

You should be looking at your repo on github now, with just a README in it. Click on the README, and then click on the link which says “raw” just on the top-right of the file. You are hopefully looking at the content of the README – make a note of the url, for example: https://raw.github.com/mjg123/mjg-repo/master/README. The fact that we can see raw file contents on the github website is enough to make a maven repo.

2. Make a maven repo

So now we’ve got a way of putting things online – we just need to work out how to make that content maven-friendly. No worries. Make an empty directory next to your README, I called it repo, so its absolute location is /home/mjg/code/mjg-repo/repo.

Now find your maven project that you want to share. I used my new maven plugin, the aa-maven-plugin which shows unicorns and other lovely creatures in your build. In the pom for that you need to add:

	<distributionManagement>
		<repository>
			<id>github.repo</id>
			<url>file:///home/mjg/code/mjg-repo/repo</url>
		</repository>
	</distributionManagement>

It’s obvious that you should obviously substitute the correct directory name in the url, obviously. Then you can just go ahead and issue a mvn clean deploy and your artefact and all the necessary metadata will appear in the repo. Commit and push it, go on, I dare you.

The url for my new repo is: https://raw.github.com/mjg123/mjg-repo/master/repo. I’m sure you can work our what yours will be. Don’t worry that github seems to give you a 404 error here – that’s just how they want to handle directories without files in, but maven knows what directory structure to expect underneath this and can jump straight in to grab what it wants without concern for your puny 404s.

3. Use your new repo

I think we’re ready to use our new repo, but first something completely different: Maven allowsforces you to configure repos for dependencies separately from repos for plugins. Even the maven documentation admits that it doesn’t make any sense but that’s how it is. The example project in my repo is a plugin and I will show the code for adding a plugin repo. For a repo containing normal dependencies it’s just the same but without the word “plugin” in the XML. Now, where were we? Oh yes. Find a project where you want to use your new thing, and add this to the pom:

	<pluginRepositories>
		<pluginRepository>
			<id>mjg-repo</id>
			<url>https://raw.github.com/mjg123/mjg-repo/master/repo</url>
		</pluginRepository>
	</pluginRepositories>

Then, add your dependency or in my case plugin configuration, and build your project. You should see maven go off and download its dependencies from github so you know you’re cooking on fine English gas. If it works but doesn’t seem to hit github, pre-haps you need to remove the copy from your local repo?

4. Give a little

All this stuff, Java, Github, Maven. What does it have in common that it doesn’t share with the project in your new repo? That’s right – open source. If you look at the files in your new repo, you’ll see there’s only the binary jar there, no sign of any sources. Here’s how I modified the pom of my project to make sure the sources were included in my repo when I did my mvn clean deploy

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

5. All done

Hope that was easy enough – would love to hear in comments if this has been helpful.

Advertisements

3 Comments

Leave a Comment
  1. jule64 / Oct 30 2012 3:07 pm

    Hi I found your article while looking for ways to make my Maven project GitHub friendly. Your article is very helpful. I was wondering though if it is possible to create and change branches easily (for example from prod to dev) once the github-Maven project is created?

  2. marrowboy / Oct 30 2012 8:47 pm

    Not 100% sure without testing it. But it looks like the word “master” in the URL is the branch name. So if you wanted to have a “dev” repo and a “prod” repo you could just have them as separate branches in git and they would both be available online. A bit of an abuse of the branching mechanism, but hey – free repo online!

  3. Welington Veiga (@welingtonveiga) / Nov 7 2012 10:02 pm

    Thank you!
    My repo is working fine!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: