Pitfalls working with jitpack

If you work with java or the JVM a lot, you're probably familiar with build tools like maven, Gradle and the like. These are all backed by some variety of Central repository where the tools search for and retrieve dependencies usually such as Maven central. However, publishing artifacts to these repositories can be a bit of a pain, to say the least. Jitpack tries to solve this by hosting a public maven repository based on public git repositories off of popular source code hosting services.

How it works

It couldn't be easier, all you do is simply create a public project based off of Gradle, Maven, Sbt or Leiningen and Jitpack takes care of the rest. It builds the project on demand and automatically serves the artifact on demand1.

Others can add the artifact as a dependency in their project by adding jitpack as a repository and adding the dependency. For example in Gradle,

allprojects {  
    repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}

dependencies {  
        compile 'com.gitlab.nishtahir:java-meme-generator:ef51352c1f'
}

Downloading a *.jar works like any other maven repo2

mvn dependency:get  
-DremoteRepositories=https://jitpack.io 
-Dartifact=com.github.User:Repo:Tag 
-Ddest=[path]

Pitfalls to watch out for

After using Jitpack for a while, I've had to deal with a few minor annoyances that I thought I'd share in hopes that it would save you time3.

  1. Just because it's on GitHub, doesn't mean it's going to build

    Jitpack only builds and serves the resulting artifact. It doesn't guarantee that the code is actually going build. If you're unable to locate an artifact, the build has probably failed.

    The minute you have any problems with artifacts being served, the first place you should check is the Jitpack log for the build.

  2. Avoid using -SNAPSHOT builds.

    The -SNAPSHOT version basically tells Jitpack that you want the latest commit on the master branch. However, it's just a ticking time bomb just waiting to go off. The build changes whenever the new commits are added and you never know what's going to be in there.

    A better alternative is to always stick with release builds, or reference specific commit IDs.

    That way you always know what's going to be in them. One might be concerned that the branch history may change along with commit IDs but as far as I can tell Jitpack doesn't delete archived copies and continues to serve them.

  3. Jitpack works with wrappers and will always use them if they are available.

    This is true for maven wrappers4 as well5. This pretty much means that you should do the same if you forget to upload the wrapper *.jar files, the project won't build. You should do the same in your CI setup to try to keep the build consistent.

  4. Keep your publish plugin up to date

    This is true especially for the android-maven plugin if you are building with gradle. Gradle 2.14.1 doesn't play nicely with the recommended android-maven-gradle-plugin:1.3, however it does work with android-maven-gradle-plugin:1.4.1.

Footnotes and references
  1. Jitpack.io. (2016). JitPack.io. [online] Available at: https://jitpack.io/docs/ [Accessed 29 Jul. 2016].

  2. Coderwall. (2015). Download an artifact from JitPack.io using Maven (Example). [online] Available at: https://coderwall.com/p/qbozzq/download-an-artifact-from-jitpack-io-using-maven [Accessed 30 Jul. 2016].

  3. I pretty much just poured through the documentation so that you don't have to :)

  4. GitHub. (2016). takari/maven-wrapper. [online] Available at: https://github.com/takari/maven-wrapper [Accessed 19 Aug. 2016].

  5. Jitpack.io. (2016). Android - JitPack.io. [online] Available at: https://jitpack.io/docs/ANDROID/ [Accessed 21 Aug. 2016].

  6. As far as I could tell, it's an undocumented feature as at the time of writing.