News and Notes from the Makers of Nexus | Sonatype Blog

Maven Tips and Tricks: Using GitHub

Written by Tim OBrien | September 08, 2009

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):

   mvn clean
   git init
   git add -A
   git commit -m "Importing the git-demo project"
   git remote add origin git@github.com:tobrien/git-demo.git
   git push origin master

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:

 <scm>
	<connection>scm:git:git@github.com:tobrien/git-demo.git</connection>
	<url>scm:git:git@github.com:tobrien/git-demo.git</url>
	<developerConnection>scm:git:git@github.com:tobrien/git-demo.git</developerConnection>
  </scm>

After the scm element, add the following build element which forces Maven to use the most recent version of the maven-release-plugin:

  <build>
<plugins>
<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-release-plugin</artifactId>
        <version>2.0-beta-9</version>
      </plugin>
    </plugins>
  </build>

Add the pom.xml to the next commit, commit your changes, and push to GitHub:

  git add pom.xml
  git commit -m "Configuring POM for GitHub project"
  git push

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".

canning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building git-demo
[INFO]    task-segment: [release:prepare] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] [release:prepare {execution: default-cli}]
[INFO] Resuming release from phase 'scm-check-modifications'
[INFO] Verifying that there are no local modifications...
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git status
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] nothing added to commit but untracked files present (use "git add" to track)
[INFO] Checking dependencies and plugins for snapshots ...
What is the release version for "git-demo"? (com.sonatype.demo:git-demo) 1.0: :
What is SCM release tag or label for "git-demo"? (com.sonatype.demo:git-demo) git-demo-1.0: :
What is the new development version for "git-demo"? (com.sonatype.demo:git-demo) 1.1-SNAPSHOT: :
[INFO] Transforming 'git-demo'...
[INFO] Not generating release POMs
[INFO] Executing goals 'clean verify'...
[WARNING] Maven will be executed in interactive mode, but no input stream has been configured for this MavenInvoker instance.
[INFO] [INFO] Scanning for projects...
[INFO] [INFO] ------------------------------------------------------------------------
[INFO] [INFO] Building git-demo
[INFO] [INFO]    task-segment: [clean, verify]
[INFO] [INFO] ------------------------------------------------------------------------
[INFO] [INFO] [clean:clean {execution: default-clean}]
[INFO] [INFO] [resources:resources {execution: default-resources}]
[INFO] [WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] [INFO] skip non existing resourceDirectory /Users/tobrien/temp/git-demo/src/main/resources
[INFO] [INFO] [compiler:compile {execution: default-compile}]
[INFO] [INFO] Compiling 1 source file to /Users/tobrien/temp/git-demo/target/classes
[INFO] [INFO] [resources:testResources {execution: default-testResources}]
[INFO] [WARNING] Using platform encoding (MacRoman actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] [INFO] skip non existing resourceDirectory /Users/tobrien/temp/git-demo/src/test/resources
[INFO] [INFO] [compiler:testCompile {execution: default-testCompile}]
[INFO] [INFO] Compiling 1 source file to /Users/tobrien/temp/git-demo/target/test-classes
[INFO] [INFO] [surefire:test {execution: default-test}]
[INFO] [INFO] Surefire report directory: /Users/tobrien/temp/git-demo/target/surefire-reports
[INFO]
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.sonatype.demo.AppTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.032 sec
[INFO]
[INFO] Results :
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] [INFO] [jar:jar {execution: default-jar}]
[INFO] [INFO] Building jar: /Users/tobrien/temp/git-demo/target/git-demo-1.0.jar
[INFO] [INFO] ------------------------------------------------------------------------
[INFO] [INFO] BUILD SUCCESSFUL
[INFO] [INFO] ------------------------------------------------------------------------
[INFO] [INFO] Total time: 5 seconds
[INFO] [INFO] Finished at: Tue Sep 08 17:35:35 CDT 2009
[INFO] [INFO] Final Memory: 24M/80M
[INFO] [INFO] ------------------------------------------------------------------------
[INFO] Checking in modified POMs...
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git add pom.xml
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git status
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git commit --verbose -F /var/folders/qR/qRpEDfQcFPmRZpsXgPHOok+++TM/-Tmp-/maven-scm-2142457355.commit pom.xml
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git push
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Tagging release with the label git-demo-1.0...
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git tag -F /var/folders/qR/qRpEDfQcFPmRZpsXgPHOok+++TM/-Tmp-/maven-scm-1032558296.commit git-demo-1.0
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git push origin git-demo-1.0
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git ls-files
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Transforming 'git-demo'...
[INFO] Not removing release POMs
[INFO] Checking in modified POMs...
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git add pom.xml
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git status
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git commit --verbose -F /var/folders/qR/qRpEDfQcFPmRZpsXgPHOok+++TM/-Tmp-/maven-scm-1856882176.commit pom.xml
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Executing: /bin/sh -c cd /Users/tobrien/temp/git-demo && git push
[INFO] Working directory: /Users/tobrien/temp/git-demo
[INFO] Release preparation complete.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 24 seconds
[INFO] Finished at: Tue Sep 08 17:35:45 CDT 2009
[INFO] Final Memory: 14M/80M
[INFO] ------------------------------------------------------------------------

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.
View full post