Releasing Maven projects to Github

This is a quick-start guide to deploying
Maven projects to a remote repository and then using the
maven-release-plugin to publish them on
GitHub.

Deploying to a remote repository

When you perform a

mvn install

command it copies the generated artifacts to your local repository. This makes it accessible to your other projects. This is ideal if you are working on a single machine. At home I’m working on a different project
which also wants to use this module. I have several options:

Install JAR manually using

mvn install-file

. This is far from ideal as I’ll have to run the command every time the JAR is updated.
I can clone my source repository at home, and install the module as normal. I may not however have access to the repository, or may not want the source code. It also means I’ll have to checkout the source code whenever I want to receive updates.
Install dependency from a repository. This requires deploying my module to a remote Maven repository. Fortunately I can use my
Dreamhost web space as a Maven repository is simply and organised structure of folders and pom files.

Deploying to a repository appears to be the easiest choice. Assuming you have a remote server you have SSH and HTTP access to then adding the following to your pom.xml will deploy the module remotely.

<distributionManagement>
<repository>
<id>release-repository</id>
<name>Repository Name</name>
<url>scp://server.address/home/user.name/path/to/dir/maven/releases</url>
</repository>
<snapshotRepository>
<id>snapshot-repository</id>
<name>Repository Name</name>
<url>scp://server.address/home/user.name/path/to/dir/maven/snapshots</url>
</snapshotRepository>
</distributionManagement>

In this fragment I’ve defined 2 repositories. One for releases, and another for snapshots. Running the

mvn deploy

will ordinarily deploy to the

release-repository

repository. If the version number is appended with

-SNAPSHOT

the code will be deployed to the snapshot repository.

Other projects which want to use this module now need to add the repositories to their pom.xml.

<repository>
<id>release-repository</id>
<name>Release Repository</name>
<url>http://server.address/path/to/dir/maven/releases</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>snapshot-repository</id>
<name>Snapshot Repository</name>
<url>http://server.address/path/to/dir/maven/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>

With this configuration when I deploy a snapshot version of my module it will be uploaded to the remote snapshot-repository. Then when update my projects at home the latest snapshot will be downloaded.

Releasing versions

When I release a version of my module I take the following actions:

Commit any modifications
Remove the

-SNAPSHOT

from the version number
Deploy the module to the

release-repository

Tag the source code with the version number
Increment the version number and append

-SNAPSHOT

All of this can be automated using the
maven-release-plugin. The maven-release-plugin requires that you have the

<scm>

elements set up in your pom.xml. I’m storing my code in
GitHub so my

<scm>

settings resemble the following:

<scm>
<connection>scm:git:git://github.com/username/project.git</connection>
<url>scm:git:git://github.com/username/project.git</url>
<developerConnection>scm:git:git://github.com/username/project.git</developerConnection>
</scm>

You also need to enable the maven-release-plugin by adding it to the

<plugins>

section in the pom.xml

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
</plugin>

To perform a release you need to run the following goals:

mvn release:prepare release:perform

You can read more about using the maven-release-plugin with
GitHub on
Sonatype’s website and
Don Brown’s blog