Tagging

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

Available only in Nexus Repository 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. 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

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.

Wait Query Parameter

When associating a tag with a component using the Tag Association REST API, the optional wait query parameter controls whether the API waits for the repository search index to update before returning a response.

Because tags are indexed asynchronously, there may be a short delay before a newly associated tag becomes searchable. The wait parameter determines whether the request waits for indexing to complete.

Parameter

Parameter	Type	Default	Description
`wait`	boolean	true	Determines whether the API waits for search indexing to complete before returning the response.

Behaviour

Value	Behavior	Recommended Use
`wait=true`	Waits approximately 2 seconds for the search index to update before returning. Tags are immediately searchable once the API returns 200 OK.	Recommended for most use cases, including automation scripts and single tagging operations.
`wait=false`	Returns immediately (typically under 100 ms). Tag indexing occurs asynchronously and search results may take approximately 2–7 seconds to reflect the change.	Recommended for bulk tagging operations where immediate searchability is not required.

Examples

Default behavior (wait=true)

The API waits for indexing to complete before returning.

POST /service/rest/v1/tags/associate/my-tag?repository=repo&name=component

Fast mode (wait=false)

Returns immediately while indexing continues asynchronously.

POST /service/rest/v1/tags/associate/my-tag?repository=repo&name=component&wait=false

Important

The default value for wait is true.
Using wait=true ensures that tags can be immediately used in search queries or tag-based operations after the API request completes.
Using wait=false improves performance when associating tags in bulk operations, but newly associated tags may not be immediately searchable.

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.