How to Create and Release a JAR to Maven Central

i spend most of my time with java writing stand-alone applications to support testing or code that we run as part of ci. i haven’t had to create a library that i make accessible to other people through maven central.

i thought it was about time i did so.

in this post, i’ll describe what i did and how i got a .jar in maven central.

what is the library?

as part of my selenium webdriver online training course , i created a ‘driver manager’ to allow code to more easily run across different browsers. it works fine for the context of my course. over time, i’ve started splitting the course source into multiple parts:

• getting started project .
• continuous integration project .
• in addition to the main code on the course.

and i’ve had to copy the driver.java into the continuous integration project.

i decided to pull it out into a separate library and make it accessible via maven central, so it will be easier for people taking the course to use the driver class in their own code.

and i can start maintaining it as a project on its own merits with better code and better flexibility, rather than something that just supports the course.

summary of what to do

what follows is a ‘checklist’ created from my notes about how i released it:

• start on “maven guide central repository upload” page
  • https://maven.apache.org/guides/mini/guide-central-repository-upload.html .
  • learn the need for pgp signing.
  • learn the basic format for pom.
  • read the up-to-date pom documentation linked to
    • http://central.sonatype.org/pages/requirements.html
    • set up pom
      • coordinates, name, description, url, license, developer, scm.
  • find the link to the “open source software repository hosting (ossrh)” guide
• follow the “open source software repository hosting (ossrh)” guide.
  • http://central.sonatype.org/pages/ossrh-guide.html .
  • follow steps to create jira account and ticket to access ossrh.
• read the maven deploy guide
  • http://central.sonatype.org/pages/apache-maven.html
  • add distributionmanagement section in the pom.
  • edit the .m2\settings.xml file to include the ossrh details.
    • https://maven.apache.org/settings.html
• read this sonatype blog post on how to configure gpg signing:
  • http://www.sonatype.org/nexus/2015/01/08/deploy-to-maven-central-repository/
  • read the full instructions on sonatype
    • http://central.sonatype.org/pages/working-with-pgp-signatures.html
  • https://www.gnupg.org/download/index.en.html
    • i downloaded 2.3.3.
    • gpg --gen-key
    • rsa and rsa.
    • 2048 bits long.
    • set expiry.
    • upload your public key.
      • this is mentioned on http://central.sonatype.org/pages/working-with-pgp-signatures.html .
      • note : make sure you do this. i forgot and my final deploy failed. do this now and all will go swimmingly.
• use mvn clean deploy to create a staging release.
  • make sure you get the groupid correct.
    • i had co.uk.compendiumdev as groupid instead of uk.co.compendiumdev so it didn’t deploy to staging.
    • i saw other jira tickets with similar problems, so it is a common mistake.
• use staging release in a project.
  • http://central.sonatype.org/pages/apache-maven.html
  • "snapshot versions are not synchronized to the central repository. if you wish your users to consume your snapshot versions, they would need to add the snapshot repository to their nexus repository manager, settings.xml, or pom.xml. successfully deployed snapshot versions will be found in https://oss.sonatype.org/content/repositories/snapshots "
  • see this guide on how to add a repository into your pom.xml https://maven.apache.org/guides/mini/guide-multiple-repositories.html
• create a test project using staging.
  • for example, https://github.com/eviltester/selenium-driver-manager-example
  • the above project uses my library and has comments in the pom.xml and the repository configuration for using the -snapshot release on osshr staging.
• create a full release.
  • http://central.sonatype.org/pages/apache-maven.html
  • “performing a release deployment.”
  • use “performing a release deployment with the maven release plugin”
    • https://youtu.be/dxr4pj_zs-0?t=3m14s
  • rename to remove -snapshot
  • mvn clean deploy
• synchronize to maven central
  • add a comment to my jira ticket on sonatype, and they enabled synchronization to maven central.
  • wait an hour or so
  • project appears on maven central
• amend my ‘test’ project to use the version from maven central
  • for example, https://github.com/eviltester/selenium-driver-manager-example
• done

now that i have a groupid that will synchronize to maven central, it should be a simpler process if i want to create any future libraries.

a bit more detail

the documentation i linked to is pretty good. i mostly just copied the information from there.

and you can see the results in the released library code:

• https://github.com/eviltester/selenium-driver-manager

and the sample project that uses the library:

• https://github.com/eviltester/selenium-driver-manager-example

changed my code to use minimal libraries

one change i made to the library pom.xml that is different from my normal use of the code in projects is that i decided not to include the full version of selenium webdriver — which i normally do when i use it:

for instance,

<dependency>
   <groupid>org.seleniumhq.selenium</groupid>
   <artifactid>selenium-server</artifactid>
   <version>3.0.1</version>
</dependency>

instead, i wanted the minimum i could add, as i know that the projects using it will be incorporating the full version of selenium webdriver.

so i just used the java interface:

<dependency>
    <groupid>org.seleniumhq.selenium</groupid>
    <artifactid>selenium-java</artifactid>
    <version>3.0.1</version>
</dependency>

configuring repositories in the pom.xml

i haven’t had to do this for a long time. i vaguely remember doing this in the past as a workaround for some local issue we had.

in order to access the -snapshot release version of the library, i have to have the repository configured in my pom.xml:

<!-- to use snapshot versionsof the driver manager we need to use the oss nexus repo -->

<repositories>
    <repository>
        <id>osshr</id>
        <name>osshr staging</name>
        https://oss.sonatype.org/content/repositories/snapshots
    </repository>
</repositories>

i imagine that this might prove a useful workaround if i ever encounter a site that has configured the maven config via settings that we are unable to access easily .

deploy was easier than i thought

i haven’t used the release deploy in maven before. and the instructions had a whole bunch of commands:

//perform a release deployment to ossrh with

mvn release:clean release:prepare

//by answering the prompts for versions and tags, followed by

mvn release:perform

but in the end, i didn’t have to do this. i changed the version to remove -snapshot and it ‘released’ when i did a mvn clean deploy .

tagging a release on github

i haven’t ‘released’ on github before, so i created a release via the github gui on the releases page:

• https://github.com/eviltester/selenium-driver-manager/releases

gotchas

what went wrong?

i tried to use a groupid that i don’t own

i’ve been pretty laissez-faire with my groupids in my projects and high-level package names because i’ve never released one before. but to use maven central you need to have a domain that you own. and someone has snapped up the .com that i often use in my code, so i needed to use the .co.uk that i own.

i might well start changing the code that i create to use this new groupid now.

i put my groupid the wrong way around

i tried mvn clean deploy for a snapshot release and i received:

[error] failed to execute goal org.sonatype.plugins:nexus-staging-maven-plugin:
1.6.7:deploy (injected-nexus-deploy) on project selenium-driver-manager:
failed to deploy artifacts: could not transfer artifact co.uk.compendiumdev
:selenium-driver-manager:jar.asc:javadoc:3.0.1-20161020.083347-1 from/to
ossrh (https://oss.sonatype.org/content/repositories/snapshots):
access denied to: https://oss.sonatype.org/content/repositories/snapshots/co/uk/
compendiumdev/selenium-driver-manager/3.0.1-snapshot/
selenium-driver-manager-3.0.1-20161020.083347-1-javadoc.jar.asc,
reasonphrase: forbidden. -> [help 1]

i checked that my credentials were correct by logging into the oss nexus system . my issue was that instead of using groupid (uk.co.compendiumdev), i mistakenly used co.uk.compendiumdev.

so don’t do that.

i forgot to release the gpg key

i forgot to release the gpg key when i created it, so i ended up trying to do a final release and seeing the following error during mvn clean deploy :

[error]     * no public key: key with id: (xxxxxxxxxxxxx) was not
able to be located on
http://pool.sks-keyservers.net:11371/.
upload your public key and try the operation again.

make sure you do this early in the process.  also, i had to wait 10-20 minutes before it was accessible. to check, visit the site you uploaded to and then search for the key. i had to search for the key id with 0x in front of it:

• 0x740585a4
• and not 740585a4

http://pool.sks-keyservers.net/pks/lookup?search=0x740585a4

when it was available from the search, then i could mvn clean deploy .

future work

i still have a lot to learn here.

as a beginner:

• i’ve added a lot of ‘stuff’ to the pom.xml that i don’t fully understand and need to research.
• i’m sure i’m taggging the release on github inefficiently.
• i’ve only done one release so i’m not sure if it is fully setup yet.
• i do this manually and haven’t added a ci deploy — when i do i’ll read the sonatype blog post more carefully .

and i have an actual todo list:

• i need to document the library and example in more detail if i want usage to spread beyond my course.
• i need to amend my wdci and course code to use the library.

but it was a lot less daunting than i expected, and the documentation was pretty clear, and the osshr team was very helpful in getting me set up. i was very impressed given that the oss staging repositories and syncing to maven central is a free service.

i hope that helps someone on the road to making their release. all in all, it was a good learning experience.

references

• https://maven.apache.org/guides/mini/guide-central-repository-upload.html
• http://central.sonatype.org/pages/requirements.html
• http://central.sonatype.org/pages/ossrh-guide.html
• https://maven.apache.org/settings.html
• http://www.sonatype.org/nexus/2015/01/08/deploy-to-maven-central-repository/
• https://www.gnupg.org/download/index.en.html
• https://maven.apache.org/guides/mini/guide-multiple-repositories.html
• http://central.sonatype.org/pages/apache-maven.html
• http://central.sonatype.org/pages/working-with-pgp-signatures.html
• the jira that i used during the setup process
  • https://issues.sonatype.org/browse/ossrh-25690
• my example project
  • https://github.com/eviltester/selenium-driver-manager-example
• i ‘cribbed’ from another github library that was using webdriver for tips
  • https://github.com/bonigarcia/webdrivermanager