Sonatype Blog: Latest Posts

Maven Tips and Tricks: Using GitHub

Sonatype uses GitHub to host a number of projects including all of our books. It has been a very valuable tool for us, and we’ve already seen great benefits. The social, interactive nature of the tool allows people interested in the book to keep up with the development of the content, and we’ve already had a few contributors show up and help us write more content. Contributors can fork our books, add whole sections or correct typod and then make a simple pull request that notifies us of the changes. Because we find it so useful, I thought I’d take some time to detail the process of connecting a new Maven project to GitHub. The following post details the process of creating a new GitHub repository, importing a Maven project, and then configuring the SCM element in your project’s POM. Once you’ve done that, you can start using the Maven Release plugin to automate the SCM operations that accompany a release.

Step 1.Install Git on your local machine. If you don’t know how to do this, don’t worry, GitHub is an example of a site that values great documentation, and they have a number of helpful guides for Windows, Mac OS X, and Linux.

Step 2.Sign up for a GitHub account if you don’t already have one.

Step 3. Once you create an account, you’ll need to load your public SSH key into GitHub. When you run git, or more importantly when Maven runs Git, it isn’t going to prompt you for a username and password, it relies upon key-based authentication in SSH. Again, if you don’t know how to do this, follow one of these GitHub help documents: Windows, Mac OS X, and Linux.

To add a public key (you can have several associated with your account), login, click on “account”, and then click on “add another public key” under the section that lists public keys.

Step 4. If you don’t already have Maven installed, download it from http://maven.apache.org and add it to your PATH. If you are looking for more detailed instructions, we have an entire chapter on the Maven installation process in Maven: The Definitive Guide.

If you can run “mvn” and “git” from the command line, you are ready to start creating a project and importing it into a new GitHub repository.

Step 5. Create a new Maven project using the archetype:generate goal. Run “mvn archetype:generate” from the command line, supply a groupId, artifactId, package name, version, and use the default quickstart Archetype.

For the purposes of this blog entry, I’ll assume you used the following parameters:

groupId: com.sonatype.blog

artifactId: git-demo

version: 1.0-SNAPSHOT

package name: com.sonatype.blog

Step 6. Change directories into the newly created “git-demo” directory and run “mvn clean install” to make sure that you can successfully build the quickstart project.

Step 7. Create a new GitHub repository. Login, and click on the GitHub logo in the upper left-hand of the web page, you should then see a list of your repositories on the right-hand side of the screen. Click on “Create a New One” next to the words “Your Repositories” (as shown below)

For the purposes of this post, I used the following values:

Once your new GitHub repository is created, GitHub will load the repository and show you some instructions. At this point, you’ll want to import the project you just created into your new GitHub repository.

Step 8. From the “git-demo” project directory, execute the following commands (substitute your Git user name for “tobrien” in the commands listed below):

After running these commands, return to the GitHub interface, and you should see that your GitHub project is now full of the contents of the git-demo project. While you’ve added the project to GitHub, you still haven’t configured your Maven project to interact with GitHub, let’s do that now….

Step 9. Open up the pom.xml file of the git-demo project and add the following scm element right before the closing project element. Make sure to substitute your account name for the instances of “tobrien” in the XML snippet shown below:

Step 10. Run the Maven Release Plugin to cut the 1.0 release. Since our quickstart project is at version 1.0-SNAPSHOT, running “mvn release:prepare” is going to update the version to 1.0, commit the changes to a git-demo-1.0 tag, and then increment the version to 1.1-SNAPSHOT. Do to this, run “mvn release:prepare”.

Step 10. After a release:prepare, the logical next step is to run a release:perform. release:perform exports the newly created git-demo-1.0 tag, builds the project and then calls deploy. If you run “release:perform” without a distributionManagement section of your POM you are going to get an error, but run it anyway just to see what the Maven Release Plugin does.

The next step on your journey involves the configuration of the distirbution management settings and the deployment of your project’s artifacts to a repository manager. Once you do that, you can completely automate the process of releasing, updating source control, and distributing your binary artifacts to a repository manager.