Tagging

Available in Nexus Repository Manager Pro Only

Overview

Tagging is a feature available in Nexus Repository Manager Pro that provides the ability to mark a set of components with a tag so they can be logically associated to each other. The usage of the tags is up to you but the most common scenarios would be a CI build ID for a project (e.g. project-abc-build-142) or a higher level release train when you are coordinating multiple projects together as a single unit (e.g. release-train-13). Tagging is used extensively by the Staging feature.

It should be noted that tags are applied at the component level and not to individual assets.  

Endpoints

Tagging capabilites have been made available by way of a REST API. For more details on how to access and use these endpoints via an interactive UI please see the REST and Integration API page.

Add Tag

POST /service/rest/v1/tags 

This endpoint allows us to create a tag. Here is a simple example:

curl -u admin:admin123 -X POST --header 'Content-Type: application/json' http://127.0.0.1:8081/service/rest/v1/tags \
  -d '{
    "name": "project-abc-142",
    "attributes": {
        "jvm": "9",
        "built-by": "jenkins"
    }
}'

The name field cannot exceed 256 characters and can only contain letters, numbers, underscores, hyphens and dots and cannot start with an underscore or dot. The attributes field can contain any valid JSON data that might assist you. There is a maximum size of 20k for the attributes field.

The response contains two additional timestamp fields to represent when the tag was first created and last updated. These two fields are set automatically and are ignored if sent in a POST or PUT.

{
  "name": "project-abc-142",
  "attributes": {
    "jvm": "9",
    "built-by": "jenkins"
  },
  "firstCreated": "2017-06-12T22:42:55.019+0000",
  "lastUpdated": "2017-06-12T22:42:55.019+0000"
}

List Tags

GET /service/rest/v1/tags

This endpoint allows us to iterate through a listing of all the tags.

This endpoint has no parameters:

curl -u admin:admin123 -X GET http://127.0.0.1:8081/service/rest/v1/tags

Typically this will produce a response that is the first page of many tags, as such:

{
    "items": [
        {
            "name": "project-abc-142",
            "attributes": {
                "jvm": "9",
                "built-by": "jenkins"
            },
            "firstCreated": "2017-06-12T22:42:55.019+0000",
            "lastUpdated": "2017-06-12T22:42:55.019+0000"
         },
         {
            "name": "project-abc-456",
            "attributes": {
                "jvm": "9",
                "built-by": "jenkins"
            },
            "firstCreated": "2017-06-13T22:24:55.019+0000",
            "lastUpdated": "2017-06-13T22:24:55.019+0000"
         }
    ],
    "continuationToken": null
}

This endpoint uses a pagination strategy that can be used to iterate through all the tags if desired.

Note that the ordering of the tags is consistent across multiple queries but it is not alphabetical.

UI Tip

It is also possible to see components associated with a given tag via the UI. You can do this by navigating to the Tags section of the Browse menu, selecting a tag and clicking Find Tagged Components. This same behavior is doable by doing a custom search using the Tag criteria.

Get Tag

GET /service/rest/v1/tags/{tagName}

This endpoint allows us to get details about an individual tag.

curl -u admin:admin123 -X GET http://127.0.0.1:8081/service/rest/v1/tags/project-abc-142
{
  "name": "project-abc-142",
  "attributes": {
    "jvm": "9",
    "built-by": "jenkins"
  },
  "firstCreated": "2017-06-12T22:42:55.019+0000",
  "lastUpdated": "2017-06-12T22:42:55.019+0000"
}

Update Tag

PUT /service/rest/v1/tags/{tagName}

This endpoint allows us to update the attributes of a single tag. Note that the tag name cannot be changed, nor can the timestamp fields.

curl -u admin:admin123 -X PUT --header 'Content-Type: application/json' http://127.0.0.1:8081/service/rest/v1/tags/project-abc-142 -d '{
    "attributes": {
        "jvm": "9",
        "built-by": "bob"
    }
}'
{
  "name": "project-abc-142",
  "attributes": {
    "jvm": "9",
    "built-by": "bob"
  },
  "firstCreated": "2017-06-12T22:42:55.019+0000",
  "lastUpdated": "2017-06-13T21:42:55.019+0000"
}

Associate Components with a Tag

POST /service/rest/v1/tags/associate/{tagName}

This endpoint allows you to search for components and associate them to an existing tag. Note that this endpoint does not create a tag if it does not exist.

curl -u admin:admin123 -X POST 'http://127.0.0.1:8081/service/rest/v1/tags/associate/project-abc-142?repository=my-company&group=com.mycompany&name=project-abc&version=2.1.1'

In this example we are searching within a repository for a specific artifact using the group, name, and version. See Search API for details on how to search for components.

{
    "status": 200,
    "message": "Association successful",
    "data": {
        "components associated": [
            {
                "name": "project-abc",
                "group": "com.mycompany",
                "version": "2.1.0"
            }
        ]
    }
}

The response contains a collection of all the components that were succesfully associated to the tag. This response can be used to assert that the association worked as expected.

Tagging During Component Upload

Tagging components can also be accomplished by including a tag when exercising the upload component REST endpoint provided by the Components API.  In the example below, we have specified the tag to be associated with the component being uploaded by adding "-F tag=project-abc-142" to the component upload call.  Additionally, components can also be uploaded and tagged by way of the user interface.

curl -v -u admin:admin123 -X POST 'http://localhost:8081/service/rest/v1/components?repository=my-company' \
   -F groupId=com.mycompany \
   -F artifactId=project-abc \
   -F version=2.1.1 \
   -F asset1=@project-abc-2.1.1.jar \
   -F asset1.extension=jar \
   -F tag=project-abc-142

Disassociate Components from a Tag

DELETE /service/rest/v1/tags/associate/{tagName}

This endpoint allows you to search for components and disassociate them from a tag. Note that this endpoint is the same as the assocation endpoint, it just uses a DELETE instead of a POST.

curl -u admin:admin123 -X DELETE 'http://127.0.0.1:8081/service/rest/v1/tags/associate/project-abc-142?repository=my-company&group=com.mycompany&name=project-abc&version=2.1.1'
{
    "status": 200,
    "message": "Disassociation successful",
    "data": {
        "components disassociated": [
            {
                "name": "project-abc",
                "group": "com.mycompany",
                "version": "2.1.1"
            }
        ]
    }
}

Privileges

Tagging is controlled by the following privileges.

nx-tags-all

Allows all tagging actions.

nx-tags-associate

Allows the association of tags to components located in repositories the user has browse privileges to as well as the viewing of tags.

nx-tags-create

Allows the creation and viewing of tags.

nx-tags-delete

Allows the deletion and viewing of tags.

nx-tags-disassociate

Allows the disassociation of tags from components located in repositories the user has browse privileges to as well as the viewing of tags.

nx-tags-read

Allows the viewing of tags.

nx-tags-update

Allows the update and viewing of tags.

Cleanup Task

Having a CI system automatically tag every build can result in an overabundance of tags. The Admin - Cleanup tags task allows admins to delete tags based on the following criteria:

  • Age (in days) of when the tag was first created (default is 0 days)
  • Age (in days) of when the tag was last modified (default is 0 days) 
  • A regular expression on the tag name (e.g. project-abc-.*)

If multiple options are selected then both criteria will need to match on the tag. Additionally you can select to delete the components associated with the tag. This option can be restricted to a specific repository or format.

In situations where a component has two tags associated with it and the tag clean up task has been configured to delete the components, that component will be deleted even when the clean up task only matches on one of the tags. For example, if component 'A' is tagged with 'build-123' and 'dev-build-123' and the tag clean up task was configured to clean up tag 'dev-build-123' AND delete components associated with it, component 'A' will be deleted. Tag 'build-123' being associated with the component does not prevent the deletion.


The task log for the Admin - Cleanup tags task contains the tags (and components if selected) that have been deleted. See the Task Logging section on the System Configuration page for more details. 

Best Practices

The following are some best practice recommendations for using the tagging functionality:

  • Use short tag names and attributes to maximize performance of tag related operations and storage utilization. Maintaining a large number of tags with attributes of maximum allowable size (20k) could result in undesirable performance degradation.
  • Proactively use the Admin - Cleanup tags task to clean up unused tags. The Admin - Cleanup tags task provides configuration options to support routine removal of aged or unused tags and the associated components (if desired).
  • Use a tag naming scheme that will ensure uniqueness of created tags and prevent naming collisions and potential interuptions to CI pipeline workflows.