Tutorial: Create a Jenkins Plugin to integrate Jenkins and Nexus Repository


In this article you will learn how to write a Jenkins CI Plugin and how to use the REST API from the Sonatype Nexus repository. I am using Maven and Jersey (JAX-RS) for the project. The complete source code is hosted on github [2]. I hope this blog will encourage you to write your own Jenkins plugins and share them with the community. Have fun.

There comes a time in every developers life when you need write your own extension, addon or plugin when using open source software. In my case I was looking for a way to improve the Continuous Delivery Pipeline we setup using the Jenkins CI server and the Build Pipeline Plugin in a previous blog series [1]. In particular I wanted to add additional metadata to the deployed artifacts after each successful build step. This blog article will guide you through the creation of a Jenkins plugin. After that we will enhance the plugin to do some actual work and add custom metadata to the artifact in the Nexus repository. The following diagram shows the different steps in the build pipeline (CommitStage, AcceptanceTestStage, PerformanceTestStage). The CommitStage builds the software artifact and deploys it to Nexus. After each successful build step metadata is added to the deployed artifact, i.e. commitStage=success.

Part I: Create your first Jenkins Plugin

Create project skeleton

To get started you can use maven-hpi-plugin to create the project blueprint. I assume you have a working version of Maven installed as well as the Java JDK. In order to use the maven-hpi-plugin you need to add the following to your Maven settings.xml that you find under $HOME/.m2/settings.xml


Once you are done with the configuration you can create the project skeleton using the hpi:create command.

$ mvn -cpu hpi:create

If you are having problems with the latest Plugin version, you can also specify the version of the plugin that you want to use.

$ mvn -cpu org.jenkins-ci.tools:maven-hpi-plugin:1.84:create

During the installation Maven will ask you for the groupId and artifactId.

Enter the groupId of your plugin: de.mb
Enter the artifactId of your plugin: nexus-metadata-plugin

The generated project should have the following layout. Jenkins uses Apache Jelly as the view technology.

marcelbirkner@ubuntu:~/workspaces/jenkins/nexus-metadata-plugin$ tree
├── pom.xml
└── src
    └── main
        ├── java
        │   └── de
        │       └── mb
        │           └── HelloWorldBuilder.java
        └── resources
            ├── de
            │   └── mb
            │       └── HelloWorldBuilder
            │           ├── config.jelly
            │           ├── global.jelly
            │           ├── help-name.html
            │           └── help-useFrench.html
            └── index.jelly

After the project skeleton is set up you can compile and package the plugin.

$ cd nexus-metadata-plugin
$ mvn package

After packaging the plugin you should find a .hpi file in the target folder.

Deploy plugin in Jenkins

In order to test the new plugin you need to have Jenkins running.

Update: Use mvn hpi:run and Jenkins will start automatically with your plugin ready for use.

Another way to get Jenkins up and running is to download the WAR file from the Jenkins mirrors [4] and start it using:

java -jar jenkins.war

Once Jenkins is up and running you can deploy your plugin.

  • Go to http://localhost:8080/
  • Manage Jenkins -> Manage Plugins -> Advanced -> Upload Plugin
  • Select nexus-metadata-plugin/target/nexus-metadata-plugin.hpi and upload to Jenkins server
  • Click “Download now and install after restart”
  • Restart Jenkins

The plugin should be available after restarting Jenkins. Now you can go and configure the plugin.

  • Jenkins Menu -> Manage Jenkins -> Configure System

You will find a section that looks like the following diagram. The plugin will print out “Hello World” if you run it during a build step. You can configure if it should greet you in english or french by selecting the checkbox.

Test Plugin

To test your new plugin you need to follow these steps:

  • Create a new Jenkins Job (i.e. Freestyle)
  • Add Build Step “Say hello world” to the Job
  • Fill out the name field in the build step
  • Build Job
  • Check command line from job

If the build is successful and you see “Hello, World!” in the command line everything is fine. Otherwise start reading from top and try again 😉 or consult the official Jenkins Plugin documentation [3].

Part II: Install and configure Nexus Repository

Adding custom metadata to artifacts in the Nexus Repository requires Nexus Professional. Another Open Source Repository that offers the same functionality is Artifactory from JFrog. Both offer a REST API and a Professional Version. In both cases you need the Pro Version to add metadata to artifacts.

Setup Nexus

To setup Nexus follow these steps:

  • Download Nexus Pro from Sonatype, http://www.sonatype.com/Products/Nexus-Professional/Purchase/Free-Trial
  • Extract the archive
  • The nexus-custom-metadata-plugin is not enabled by default. To enable it copy it to the plugin-repository folder.

cp -r nexus-professional-trial-2.0.6/nexus/WEB-INF/optional-plugins/nexus-custom-metadata-plugin-2.0.6/ 
  • Start Nexus

nexus-professional-trial-2.0.6/bin$ ./nexus start
  • Open Nexus in your browser and register for the 14 day trial version, http://localhost:8081/nexus
  • You will receive an Email with the Trial registration code via Email within a minute
  • Login with admin/admin123

To verify that the nexus-custom-metadata-plugin was installed successful go to Administration -> Plugin Console. There you should see the following information. If you click the links you should be forwarded to the REST API of the Plugin.

Under the same section you will find the Core Documentation as well. That one contains the Core REST API calls that you can use by default. Unfortunately that API does not allow you to store metadata for artifacts.

Setup Maven Project

Under the REST API documentation you will find a client.jar that provides all the REST Models we need for calling the REST API. Therefore download the JAR and upload it to the ThirdParty repository in Nexus.

  • Download from: http://localhost:8081/nexus/nexus-custom-metadata-plugin/m2/docs/nexus-custom-metadata-plugin-client.jar

Next, you need to configure your Maven $HOME/.m2/settings.xml to use Nexus for resolving Maven artifacts. Add the following lines to the settings.xml.

      <!--This sends everything else to /public -->
      <!--Enable snapshots for the built in central repo to direct -->
      <!--all requests to nexus via the mirror -->
    <!--make the profile active all the time -->

After that we are ready to start developing the plugin.

Part III: Integrate Jenkins and Nexus with a custom Jenkins Plugin

Now that we have Jenkins and Nexus up and running we can go back to do some coding. I suggest you clone the code from my github repository. I will explain all changes I made step-by-step.

Add Dependencies

For calling the Nexus REST API’s I decided to use the Jersey Framework. Simply add the following dependencies to your pom.xml.


Configure Metadata Plugin

Rename the HelloWorldBuilder packages under src/main/java and src/main/resources to NexusMetadataBuilder.

To make the Jenkins Plugin configurable add the following lines to the global.jelly. This allows us to specify the Nexus URL and credentials in the Jenkins configuration.

  <f:section title="Nexus Metadata">
	<f:entry title="Nexus URL" field="nexusUrl"
      description="Add Nexus URL">
      <f:textbox />
	<f:entry title="User" field="nexusUser"
      description="Add Nexus User">
      <f:textbox />
    <f:entry title="Password" field="nexusPassword"
      description="Add Nexus Password">
      <f:textbox />

In the next step we add some fields that we can configure on the Job. We need to be able to tell the Plugin the Key/Value we want to store with the artifact and the location of the artifact in the Nexus repository (groupId, artifactId, version, packaging).

  <f:entry title="Key" field="key">
    <f:textbox />
  <f:entry title="Value" field="value">
    <f:textbox />
  <f:entry title="groupId" field="groupId">
    <f:textbox />
    <f:entry title="artifactId" field="artifactId">
    <f:textbox />
    <f:entry title="version" field="version">
    <f:textbox />
  <f:entry title="packaging" field="packaging">
    <f:textbox />

Now we can create the NexusMetadataBuilder.java [5] class that will put all the pieces together. This class takes care of reading the plugin configuration (NexusUrl & Credentials) as well as the configuration from the Build Job (groupId, artifactId, version, packaging). In perform Method we create the REST Client that calls out to the Nexus REST API. The first call uses the Nexus Core API and checks the status of Nexus. It should return “200 OK” when its up and running. The REST Mount Point is: /service/local/status

// setup REST-Client
ClientConfig config = new DefaultClientConfig();
Client client = Client.create(config);
client.addFilter( new HTTPBasicAuthFilter(user, password) ); 
WebResource service = client.resource( url );
listener.getLogger().println("Check that Nexus is running");
String nexusStatus = service.path("service").path("local").path("status").accept(MediaType.APPLICATION_JSON).get(ClientResponse.class).toString();
listener.getLogger().println(nexusStatus + "\n");

For the custom metadata plugin we need to encode the “subject” (location of the artifact) with Base64, which is not really RESTful in my opinion. The REST Mount Point is: /service/local/index/custom_metadata/{repository}/{subject}

String artefact = "urn:maven/artifact#"+getGroupId()+":"+getArtifactId()+":"+getVersion()+"::"+getPackaging()+"";
listener.getLogger().println("GET metadata for artefact " + artefact);
String encodedString = new String( Base64.encode( artefact.getBytes() ) );
listener.getLogger().println("POST: add new metadata to artefact " + artefact);
CustomMetadataRequest customRequest = getCustomMetadataRequest( getKey(), getValue() );
.path(encodedString).accept( MediaType.APPLICATION_JSON ).post( customRequest );

Build Plugin from Github

If you want to build the project from Github follow these steps:

cd nexus-metadata-plugin
mvn clean package

Afterwards you will find the nexus-metadata-plugin.hpi plugin in the /target folder. Once you deploy the plugin and configure each build step of the continuous delivery build pipeline the deployed artifact in Nexus will have the metadata attached, see diagram.


This has been a long tutorial but I tried to cover the most important steps. I hope you could learn a little and feel encouraged to start writing and sharing your own Jenkins Plugins. Check out the Jenkins CI homepage on how to contribute Plugins to the community.


[1] Continuous Delivery Pipeline, Continuous Delivery in the cloud
[2] Sourcecode on github, https://github.com/marcelbirkner/nexus-metadata-plugin.
[3] Jenkins Plugin Tutorial, https://wiki.jenkins-ci.org/display/JENKINS/Plugin+tutorial
[4] Jenkins Download, http://mirrors.jenkins-ci.org/war/latest/jenkins.war
[5] NexusMetadataBuilder, nexus-metadata-plugin @ github


  • Christopher

    13. August 2012 von Christopher

    You don’t need to download Jenkins and manually install your plugin during development; you can just run “mvn hpi:run” and Jenkins will start automatically with your plugin ready for use.

    • Marcel Birkner

      13. August 2012 von Marcel Birkner

      Hi Christopher, thank you for your comment. I updated the blog with your suggestion. That makes it a lot easier to test plugin changes 🙂

  • Soumyajit Mishra

    17. August 2012 von Soumyajit Mishra

    I am getting following error while trying to build it.

    [INFO] ————————————————————————
    [INFO] ————————————————————————
    [INFO] Total time: 23:22.391s
    [INFO] Finished at: Thu Aug 16 14:52:38 PDT 2012
    [INFO] Final Memory: 8M/20M
    [INFO] ————————————————————————
    [ERROR] Failed to execute goal on project nexus-metadata-plugin: Could not resol
    project de.mb:nexus-metadata-plugin:hpi:1.0: Could not find artifact org.sonaty
    om-metadata-plugin-client:jar:1.0 in repo.jenkins-ci.org (http://repo.jenkins-ci
    elp 1]
    [ERROR] To see the full stack trace of the errors, re-run Maven with the -e swit
    [ERROR] Re-run Maven using the -X switch to enable full debug logging.
    [ERROR] For more information about the errors and possible solutions, please rea
    [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/DependencyReso

    Can you please share the plugin.


    • Marcel Birkner

      17. August 2012 von Marcel Birkner

      Hi Soumyajit,

      you can find the Maven Dependency in the Nexus Pro zip file. After unpacking Nexus Pro you should find the nexus-custom-metadata-plugin-client.jar file under “optional-plugins”.
      Take that JAR file and add it to your local Maven Repository or to your Nexus installation.

      Directory: nexus-professional-trial-2.0.6-bundle\nexus-professional-trial-2.0.6\nexus\WEB-INF\optional-plugins\nexus-custom-metadata-plugin-2.0.6\nexus-custom-metadata-plugin-2.0.6\docs\

      mvn install:install-file

      For more information check the README.md file, https://github.com/marcelbirkner/nexus-metadata-plugin

      I hope that helps,

  • Kaj Kandler

    why do you use Nexus Pro? Would this work with Nexus OSS also?

    • Marcel Birkner

      25. September 2013 von Marcel Birkner

      Hi Kaj,

      the metadata plugin in Nexus 2.0.6 was only available in the Nexus Pro version as an optional plugin. In the latest version of Nexus the metadata plugin has been removed.


  • Code

    Do you know why the plugin settings disappear from the Configuration page after I restart the the service?

  • Shiraz

    [ERROR] Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.7:deploy (default-deploy) on project com.imsi: Deployment failed: repository element was not specified in the POM inside distributionManagement element or in -DaltDeploymentRepository=id::layout::url parameter -> [Help 1]
    [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
    [ERROR] Re-run Maven using the -X switch to enable full debug logging.
    [ERROR] For more information about the errors and possible solutions, please read the following articles:

    — I am getting above error on jenkins. Below are my pom & settings.xml:

    Project Rosco













    Codehaus Snapshots







    — Can you plz let me know why I am getting the error. All I want to do is running pom.xml on Jenkins. Do you have steps how to get maven 2/3 plugin on Jenkins?



Your email address will not be published.