Hosting a Maven repository on github
Since 2019 you can now use the new functionality called Github package registry.
Basically the process is:
- generate a new personal access token from the github settings
- add repository and token info in your
settings.xml
deploy using
mvn deploy -Dregistry=https://maven.pkg.github.com/yourusername -Dtoken=yor_token
You can use JitPack (free for public Git repositories) to expose your GitHub repository as a Maven artifact. Its very easy. Your users would need to add this to their pom.xml:
- Add repository:
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
- Add dependency:
<dependency>
<groupId>com.github.User</groupId>
<artifactId>Repo name</artifactId>
<version>Release tag</version>
</dependency>
As answered elsewhere the idea is that JitPack will build your GitHub repo and will serve the jars. The requirement is that you have a build file and a GitHub release.
The nice thing is that you don't have to handle deployment and uploads. Since you didn't want to maintain your own artifact repository its a good match for your needs.
Don't use GitHub as a Maven Repository.
Edit: This option gets a lot of down votes, but no comments as to why. This is the correct option regardless of the technical capabilities to actually host on GitHub. Hosting on GitHub is wrong for all the reasons outlined below and without comments I can't improve the answer to clarify your issues.
Best Option - Collaborate with the Original Project
The best option is to convince the original project to include your changes and stick with the original.
Alternative - Maintain your own Fork
Since you have forked an open source library, and your fork is also open source, you can upload your fork to Maven Central (read Guide to uploading artifacts to the Central Repository) by giving it a new groupId
and maybe a new artifactId
.
Only consider this option if you are willing to maintain this fork until the changes are incorporated into the original project and then you should abandon this one.
Really consider hard whether a fork is the right option. Read the myriad Google results for 'why not to fork'
Reasoning
Bloating your repository with jars increases download size for no benefit
A jar is an output
of your project, it can be regenerated at any time from its inputs
, and your GitHub repo should contain only inputs
.
Don't believe me? Then check Google results for 'dont store binaries in git'.
GitHub's help Working with large files will tell you the same thing. Admittedly jar's aren't large but they are larger than the source code and once a jar has been created by a release they have no reason to be versioned - that is what a new release is for.
Defining multiple repos in your pom.xml slows your build down by Number of Repositories times Number of Artifacts
Stephen Connolly says:
If anyone adds your repo they impact their build performance as they now have another repo to check artifacts against... It's not a big problem if you only have to add one repo... But the problem grows and the next thing you know your maven build is checking 50 repos for every artifact and build time is a dog.
That's right! Maven needs to check every artifact (and its dependencies) defined in your pom.xml against every Repository you have defined, as a newer version might be available in any of those repositories.
Try it out for yourself and you will feel the pain of a slow build.
The best place for artifacts is in Maven Central, as its the central place for jars, and this means your build will only ever check one place.
You can read some more about repositories at Maven's documentation on Introduction to Repositories
The best solution I've been able to find consists of these steps:
- Create a branch called
mvn-repo
to host your maven artifacts. - Use the github site-maven-plugin to push your artifacts to github.
- Configure maven to use your remote
mvn-repo
as a maven repository.
There are several benefits to using this approach:
- Maven artifacts are kept separate from your source in a separate branch called
mvn-repo
, much like github pages are kept in a separate branch calledgh-pages
(if you use github pages) - Unlike some other proposed solutions, it doesn't conflict with your
gh-pages
if you're using them. - Ties in naturally with the deploy target so there are no new maven commands to learn. Just use
mvn deploy
as you normally would
The typical way you deploy artifacts to a remote maven repo is to use mvn deploy
, so let's patch into that mechanism for this solution.
First, tell maven to deploy artifacts to a temporary staging location inside your target directory. Add this to your pom.xml
:
<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>
Now try running mvn clean deploy
. You'll see that it deployed your maven repository to target/mvn-repo
. The next step is to get it to upload that directory to GitHub.
Add your authentication information to ~/.m2/settings.xml
so that the github site-maven-plugin
can push to GitHub:
<!-- NOTE: MAKE SURE THAT settings.xml IS NOT WORLD READABLE! -->
<settings>
<servers>
<server>
<id>github</id>
<username>YOUR-USERNAME</username>
<password>YOUR-PASSWORD</password>
</server>
</servers>
</settings>
(As noted, please make sure to chmod 700 settings.xml
to ensure no one can read your password in the file. If someone knows how to make site-maven-plugin prompt for a password instead of requiring it in a config file, let me know.)
Then tell the GitHub site-maven-plugin
about the new server you just configured by adding the following to your pom:
<properties>
<!-- github server corresponds to entry in ~/.m2/settings.xml -->
<github.global.server>github</github.global.server>
</properties>
Finally, configure the site-maven-plugin
to upload from your temporary staging repo to your mvn-repo
branch on Github:
<build>
<plugins>
<plugin>
<groupId>com.github.github</groupId>
<artifactId>site-maven-plugin</artifactId>
<version>0.11</version>
<configuration>
<message>Maven artifacts for ${project.version}</message> <!-- git commit message -->
<noJekyll>true</noJekyll> <!-- disable webpage processing -->
<outputDirectory>${project.build.directory}/mvn-repo</outputDirectory> <!-- matches distribution management repository url above -->
<branch>refs/heads/mvn-repo</branch> <!-- remote branch name -->
<includes><include>**/*</include></includes>
<repositoryName>YOUR-REPOSITORY-NAME</repositoryName> <!-- github repo name -->
<repositoryOwner>YOUR-GITHUB-USERNAME</repositoryOwner> <!-- github username -->
</configuration>
<executions>
<!-- run site-maven-plugin's 'site' target as part of the build's normal 'deploy' phase -->
<execution>
<goals>
<goal>site</goal>
</goals>
<phase>deploy</phase>
</execution>
</executions>
</plugin>
</plugins>
</build>
The mvn-repo
branch does not need to exist, it will be created for you.
Now run mvn clean deploy
again. You should see maven-deploy-plugin "upload" the files to your local staging repository in the target directory, then site-maven-plugin committing those files and pushing them to the server.
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building DaoCore 1.3-SNAPSHOT
[INFO] ------------------------------------------------------------------------
...
[INFO] --- maven-deploy-plugin:2.5:deploy (default-deploy) @ greendao ---
Uploaded: file:///Users/mike/Projects/greendao-emmby/DaoCore/target/mvn-repo/com/greendao-orm/greendao/1.3-SNAPSHOT/greendao-1.3-20121223.182256-3.jar (77 KB at 2936.9 KB/sec)
Uploaded: file:///Users/mike/Projects/greendao-emmby/DaoCore/target/mvn-repo/com/greendao-orm/greendao/1.3-SNAPSHOT/greendao-1.3-20121223.182256-3.pom (3 KB at 1402.3 KB/sec)
Uploaded: file:///Users/mike/Projects/greendao-emmby/DaoCore/target/mvn-repo/com/greendao-orm/greendao/1.3-SNAPSHOT/maven-metadata.xml (768 B at 150.0 KB/sec)
Uploaded: file:///Users/mike/Projects/greendao-emmby/DaoCore/target/mvn-repo/com/greendao-orm/greendao/maven-metadata.xml (282 B at 91.8 KB/sec)
[INFO]
[INFO] --- site-maven-plugin:0.7:site (default) @ greendao ---
[INFO] Creating 24 blobs
[INFO] Creating tree with 25 blob entries
[INFO] Creating commit with SHA-1: 0b8444e487a8acf9caabe7ec18a4e9cff4964809
[INFO] Updating reference refs/heads/mvn-repo from ab7afb9a228bf33d9e04db39d178f96a7a225593 to 0b8444e487a8acf9caabe7ec18a4e9cff4964809
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 8.595s
[INFO] Finished at: Sun Dec 23 11:23:03 MST 2012
[INFO] Final Memory: 9M/81M
[INFO] ------------------------------------------------------------------------
Visit github.com in your browser, select the mvn-repo
branch, and verify that all your binaries are now there.
Congratulations!
You can now deploy your maven artifacts to a poor man's public repo simply by running mvn clean deploy
.
There's one more step you'll want to take, which is to configure any poms that depend on your pom to know where your repository is. Add the following snippet to any project's pom that depends on your project:
<repositories>
<repository>
<id>YOUR-PROJECT-NAME-mvn-repo</id>
<url>https://github.com/YOUR-USERNAME/YOUR-PROJECT-NAME/raw/mvn-repo/</url>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
</repository>
</repositories>
Now any project that requires your jar files will automatically download them from your github maven repository.
Edit: to avoid the problem mentioned in the comments ('Error creating commit: Invalid request. For 'properties/name', nil is not a string.'), make sure you state a name in your profile on github.