Skip to main content

How can I add additional metadata to an artifact stored in Nexus Repository 2 or 3?

Rich Seddon
Updated

Overview

Visit my.sonatype.com for documentation on Nexus Repository version 2.

This article describes several methods to add custom metadata key/value pairs for artifacts deployed to Nexus Repository 2 or 3.

Preparation

Before you begin, you need to install the nexus-custom-metadata-plugin into Nexus Repository 2 or 3. 

Nexus Repository 2.7+

The plugin is installed already. However you do need to enable it explicitly by going to Administration -> Capabilities, and then adding the Custom Metadata capability.

Nexus Repository 2.6.x and Earlier

The plugin is available as an optional plugin. Move "nexus/WEB-INF/optional-plugins/nexus-custom-metadata-plugin-<version>" into "<nexus_root>/nexus/WEB-INF/plugin-repository", then restart the server.

Custom Metadata File Format

You can upload custom metadata data into Nexus using an xml file. The file will be processed as artifact metadata if it meets the following criteria:

  • File extension is ".n3" or ".xml"
  • The artifact classifier is "metadata"

Here are example contents of a metadata file which adds additional custom metadata to an artifact with GAV of "test:project:1.0" and packaging of "jar":

<urn:maven/artifact#test:project:1.0::jar>
    <urn:mycustomspace#repositoryId> "releases" ;
    <urn:mycustomspace#mavenVersion> "2.2.1" ;
    <urn:mycustomspace#releaseManager> "myusername" ;
    <urn:mycustomspace#codeCoverage> ".99" .

Upload this to to GAV test:project:1.0 with packaging jar, classifier metadata, and file extension of .n3.

Custom Metadata Deployment

There is more than one method to deploy custom metadata. Choose the option that best fits your use case.

maven-deploy-plugin

To do this with the deploy plugin you can run a command like this:

mvn deploy:deploy-file -DgroupId=com.somecompany \
-DartifactId=project \
-Dversion=1.0 \
-Dpackaging=n3 \
-Dclassifier=metadata \
-Dfile=metadata.n3 \
-DrepositoryId=releases \
-Durl=http://localhost:8081/nexus/content/repositories/releases \
-DgeneratePom=false

build-helper-maven-plugin

You can also use the build-helper-maven-plugin to have this happen automatically during your builds:

<project>  
   <build>
       <plugins>          
           <plugin>
               <groupId>org.codehaus.mojo</groupId>
               <artifactId>build-helper-maven-plugin</artifactId>
               <version>1.7</version>
               <executions>
                   <execution>
                       <id>attach-artifacts</id>
                       <phase>package</phase>
                       <goals>
                           <goal>attach-artifact</goal>
                       </goals>
                       <configuration>
                           <artifacts>
                               <artifact>
                                   <file>metadata.n3</file>
                                   <type>n3</type>
                                   <classifier>metadata</classifier>
                               </artifact>                               
                           </artifacts>
                       </configuration>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>
</project>

There is a working example project attached at the bottom of this article.

Nexus Repository 2 or 3 REST API

Another option is to use the REST API. To do this you'll need to base 64 encode the URI of your artifact. For the example above this would be the base64 encoding of "urn:maven/artifact#test:project:1.0::jar".  So you would end up with "dXJuOm1hdmVuL2FydGlmYWN0I3Rlc3Q6cHJvamVjdDoxLjA6Omphcg==".  

Then take this value, and append it to /service/local/index/custom_metadata/<repository-id>.  For the example above, you'll end up with:

http://localhost:8081/nexus/service/local/index/custom_metadata/releases/dXJuOm1hdmVuL2FydGlmYWN0I3Rlc3Q6cHJvamVjdDoxLjA6Omphcg==

Then a simple POST request can be used to add metadata:

curl -v -u admin:admin123 --data '{ "data": [{ "key": "foo", "value": "bar" }] }' --header "content-type:application/json" http://localhost:8081/nexus/service/local/index/custom_metadata/releases/dXJuOm1hdmVuL2FydGlmYWN0I3Rlc3Q6cHJvamVjdDoxLjA6Omphcg==

Updating Custom Metadata

It is possible to update already deployed custom metadata.

  1. You must change the deployment policy of the repository to "allow redeploy"
  2. You must delete the previous .n3 file before uploading a new one (this can be done via HTTP DELETE request to /service/local/repositories/<repo-id>/content/path/to/file)
    Example:
    curl -X DELETE -u admin:admin123 http://localhost:8081/nexus/service/local/repositories/releases/content/com/somecompany/project/1.0/project-1.0-metadata.n3

Related articles