Use GitHub Pages as your own maven repository

In this blog post we'll explain the process of setting up the GitHub as your maven type repository for all of your projects dependencies. As an example project, we'll use the KBImageView library that we developed. It's a beefed up Android ImageView which adjusts its aspect ratio according to the source image. Additionally, you can add border, textured border or shadow to the image view and it can be changed to circular shape. More on the image view itself in the next blog post.

Which maven repository to use?

There are several options to choose from for hosting your projects files. The most obvious one is the maven central repository provided by Sonatype, but we found that for small projects the publishing process is a little bit overkill, much like the second option, which involves setting up your Maven repository on your own server. This leaves us with the third option - GitHub.

One GitHub repo for all your maven artifacts

Since you will probably make more than one library, it would make sense to have them bundled inside one maven type repository. To distribute maven artifacts for your libraries, you can use GitHub User, Organization or Project pages. Make sure you understand the difference between them by clicking on the previous link. Since this blog is hosted on our GitHub organization pages, we've opted for project pages to host all our libraries' maven artifacts.

Step one: Create new GitHub repository under your organization/personal GitHub account

First, create a new repository on your GitHub organization or user account. We've named it repo. As mentioned in one of the previous links, to host project Pages, you have to create a branch gh-pages in your newly created repository. For a step by step guide on how to do this, click here.

Step two: Generate maven artifacts for your library

Now, back to your library project at hand. To make your library available as a gradle dependency, you have to create necessary maven artifacts for it. Thankfully, gradle has you covered on this. In your main build.gradle file add new gradle task (here's an example from KBImageView library):

createMavenArtifacts{
    repositories.mavenDeployer{
        pom.groupId = "com.kodbiro.kbimageview"
        pom.artifactId = "kbimageview"
        pom.version = "1.0" 
        repository(url: uri("repo")
    }
}

Next you will need to execute this task. You can use terminal for this by entering the following command: gradle clean build createMavenArtifacts. Other option is to use Android Studio gradle tab, find the createMavenArtifacts task and double click on it (clean the project prior to this). Either way, you should get the message BUILD SUCCESSFUL in the terminal or the gradle console (if you used Android Studio) and a new folder inside your library project called repo (or whatever you've put in the repository(url: uri("repo")) line). Contents of the newly generated folder represent your libraries' maven artifacts.

Step three: Upload maven artifacts to your organization's GitHub repo

Final step to make your library available as gradle dependency is to copy the contents of the generated folder to your repository described in step one. IMPORTANT: Make sure you push it to the gh-pages branch.

If you've done all the steps above, you should be good to go. For reference, here you can check out how our gh-pages branch of repo repository looks like.

Step four: Using the library in other projects

Now you are ready to use your library as a gradle dependency in other projects. To use it, you will have to edit your gradle files in two places. First, you need to add a new maven repository to your top level gradle file. The repository is a link to your GitHub repository created in step one. Here's what you need to add to use KBImageView library:

repositories{
   maven{
       url "http://kodbiro.github.io/repo/"
   }
}

Next, you need to add a reference to your library that you uploaded in step three. Something like this:

dependencies{
    ...
    compile 'com.kodbiro.kbimageview:kbimageview:1.0@aar'
}

That's it. Let us know in the comment section below what you think of this method of hosting your libraries and maybe give KBImageView a try :)