Skip to main content

Tagging

Note

Only available in Sonatype Nexus Repository Pro. Interested in a free trial? Start here.

Available only in Nexus Repository Manager Pro, tagging provides the ability to mark a set of components with a tag so that they can be logically associated with each other. The most common scenarios for using tags include the following:

  • A CI build ID for a project (e.g., project-abc-build-142).

  • A higher-level release train is when you are coordinating multiple projects together as a single unit (e.g., release-train-13).

The Staging feature uses tagging extensively.

Note

Tags are applied at the component level and not to individual assets.

Endpoints

Tagging capabilities are available via a REST API. For more details on how to access and use these endpoints via an interactive UI, see the REST and Integration API page. Non-administrator users will need the respective nx-tags privileges to perform the curl.

Add Tag

POST /service/rest/v1/tags

This endpoint allows you 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.

Example Response

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

This will typically produce a response that is the first page of many tags:

Example Response

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

Note

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

Example Response

{
  "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 you cannot change the tag name or 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"
    }
}'

Example Response

{
  "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 with 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'

This example shows a search within a repository for a specific artifact using the group, name, and version. See Search API for details on how to search for components.

Example Response

{
    "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 successfully associated with the tag. This response can be used to assert that the association worked as expected.

Tagging During Component Upload

You can also tag components by including a tag when exercising the upload component REST endpoint provided by the Components API. The example below specifies the tag to associate with the component being uploaded by adding "-F tag=project-abc-142" to the component upload call. You can also upload and tag components when uploading through 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 similar to the association endpoint, but it 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'

Example Response

{
    "status": 200,
    "message": "Disassociation successful",
    "data": {
        "components disassociated": [
            {
                "name": "project-abc",
                "group": "com.mycompany",
                "version": "2.1.1"
            }
        ]
    }
}

Security

Tagging is controlled by the following privileges.

Privilege

What it Allows

nx-tags-all

All tagging actions.

nx-tags-associate

View tags and associate them to components located in repositories to which the user has browse privileges.

nx-tags-create

View and create tags.

nx-tags-delete

View and delete tags.

nx-tags-disassociate

View tags and disassociate them from components located in repositories to which the user has browse privileges.

nx-tags-read

Allows the viewing of tags.

nx-tags-update

View and update tags.

For associate and disassociate, the respective user will also need the ability to browse the components, defined by the nx-repository-view browse privilege for the respective repository.

Cleanup Task

Having a CI system automatically tag every build can result in an overabundance of tags. The Admin - Cleanup tags task allows administrators 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 an administrator selects multiple options, the tag must meet both criteria. Additionally, you can select to delete the components associated with the tag; this option can be restricted to a specific repository or format.

Warning

In situations where a component has two associated tags and the tag cleanup task is configured to delete the components, the system will delete that component even when the cleanup 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 cleanup task is configured to clean up tag "dev-build-123" AND delete components associated with it, it will delete component A. The component also being tagged "build-123" will not prevent the deletion.

The task log for the Admin - Cleanup tags task contains a list of the deleted tags and components. See the task logging section on the System Configuration page for details.

Best Practices

The following are some best practice recommendations for using tagging:

  • Use short tag names and attributes to maximize the 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 the uniqueness of created tags and prevent naming collisions and potential interruptions to CI pipeline workflows.