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:

  1. 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.
  2. 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.
  3. 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