This topic outlines how to use Tags to organize and view your Harness Application and their components. It includes the following sections:
- Video Summary
- Intended Audience
- Before You Begin
- Tags 101
- Tag Format Restrictions
- Tags' Scope
- Tags and Permissions
- Applying Tags
- Filtering on Tags
- Tag Restrictions
- Managing Tags
- Account Administrators
Before You Begin
Harness Tags function like the tags on common cloud providers' platforms. Our Tags are arbitrary key-value pairs that you can apply to Harness Applications and Application components. As metadata, they facilitate organizing, searching, and filtering on these Harness entities.
Using Tags, you can overlay your organization’s structure onto Harness resources. Some sample use cases are:
- Categorizing Applications and components by team.
- Marking Applications and components for reuse, preservation, or deletion.
- Allocating costs.
Some examples of Tag keys, with representative values, are:
The final Tag example above is a key with no value. If present a component, a Tag with no value simply acts like a flag.
Tag Format Restrictions
Tag names and values are restricted to the following format:
If you are adding Tags in Workflows and Pipelines, you can use variable expressions in the names and values. Variable expressions follow the format
When the variable expression is evaluated by Harness, it does not need to meet the standard Tag format restrictions. It has no restrictions.
If a Tag uses a variable expression in its name or value, you cannot edit it in Tags Management. You must edit the Tag in a Workflow or Pipeline.
For more information, see Use Expressions in Workflow and Pipeline Tags.
Tags can be added to Harness Applications, and to the following Application components:
- Infrastructure Provisioner
Harness plans to add further tagging options.
Tags and Permissions
Your options for interacting with Tags depend on your Harness User Group permissions, as follows:
- All users can view Tags (and values) that have been applied to Applications and their components.
- Users' Application Permissions determine their ability to apply, update, and remove Tags on specific Applications and Application components. See Applying Tags, below.
- Users who have the Account Permission: Manage Tags can create Tag keys, impose Allowed Values on keys, and edit and delete keys. See Managing Tags, later in this topic.
To add a Tag to an Application or supported Application component:
- Click into the Application or component to display its Overview card: Application Overview, Environment Overview, Workflow Overview, etc. Here, you can locate and click the Add Tag link:
- In the resulting pop-up, select a key from the Tag Name drop-down:
- The Tag Value field can normally be left empty, or can accept a single free-form value (subject to Harness' restrictions on Tag values): However, if the tag has Allowed Values—indicated by a R(estricted) symbol—you must select a value from the drop-down list, as shown below:
- Click Submit to add your Tag: Each applied Tag's key and value will now appear on the Application's or component's Overview card:
Replacing Tag Values
If you click Add Tag, and then select a Tag Name that has already been applied to this Application or component, you will see the error message shown below:
This is a reminder that each Tag can have only one value on a given Application or component. You can just click on the existing Tag to type (or select) a replacement Tag Value:
Click Submit to update the tag's value.
You can remove Tags from the same Applications and components where you have Application Permissions to add (attach) Tags. Simply click the Tag's X box, then respond to the confirmation message box shown below.
Filtering on Tags
Applications, and Application components that support Tags, enable you to filter their list view by Tags and Tag values applied to those entities.
Look for a Filter button at the upper right. These are shown below (with tooltips) for the Setup > Applications list, and for a single Application's Infrastructure Provisioners page:
To filter Applications or their components by Tags:
- Click the Filter button (highlighted above).
This opens the Filter dialog, initially empty:
- The Name field enables free-text filtering of the currently displayed Harness entity (Applications or an Application component). This option will display entities whose names (or their substrings) match the text that you enter.
Harness applies AND search logic between the Name and Tags fields. So any Name string that you enter will further restrict the results of your Tags selection, and vice versa.
- Click the Tags multi-select field to open the controls shown below.
- Click the Match:All radio button to apply AND (restrictive) search logic among multiple Tag selections. Accept the default Match:Any radio button to perform an OR (inclusive) search among multiple Tags.
- Use the Search box to locate desired Tags, or Tag values, by free-text search. Or, manually scroll the list of Tags and values.
Tag names have a gray background. Tag values have a white background, and are indented after their check boxes.
- To retrieve Harness entities that match a given Tag with any value, select the Any Value check box to the Tag's right. To match only one or more specific values, select the check boxes to their left.
Within a given Tag, inclusive OR search logic is always applied among the values you select. (Remember that each Tag can take only one value on a given Application or component—so a restrictive AND search for two or more values would always return zero results.) The search logic among your selected Tags is either OR or AND—depending on your Match setting.The Tags field updates to display a running summary of your selections.
- When you are ready to display the results of your selected filter conditions, click Apply. To discard all selections and keep the dialog open to make new selections, click Clear All.
Managing Applied Filters
Once you've applied filters to an Application or component, you can adjust or remove them using controls similar to those that Harness provides for Audit Trails filters. For details, see Update or Save Filters.
Tags in Harness have these general restrictions:
- A Harness account can maintain a maximum of 500 Tag names.
- Each Application, or Application component, can have a maximum of 50 Tags applied to it.
- When applied to an Application or component, each instance of a Tag key can have only one value.
- The Tag-name prefix
harness.io/is reserved for future use by Harness.
Tag names (keys) have the following restrictions:
- Length: 1 to 128 characters.
- Allowed characters: letters, numbers, spaces,
- Names must be unique across your Harness account.
- Names are case-sensitive.
- Names must not begin with the characters
_, -or spaces.
- System tags will have the Tag-name prefix
Tag values, when applied to Applications or components, have the following restrictions:
- Length: 0 to 256 characters. (Entering a value is optional—unless the Tag key imposes Allowed Values, in which case one of those values is required.)
- Allowed characters: letters, numbers, spaces,
- Values are case-sensitive.
- Must not begin with the characters
_, -or spaces.
To access all Tags for your Harness account, select Setup > Tags Management.
This displays the Tags Management page.
Here, all Harness users can:
- View Tags. (Note the Search by Tag Name field at the top right, which filters the display.)
- View Tags' usage in the Used Values column.
- Click individual entries in the Tag Name or Used Values columns to display expanded usage details. (The Tag Usage Details modal below expands the previous display's row for the owner Tag. Within this Tag Usage Details modal, you can click the linked components to view their configuration.)
Creating Tag Keys
Users whose User Group includes the Manage Tag Account permission can create a new Tag, as follows:
- Select Setup > Tags Management page > Create Tag (upper-right corner).
- In the resulting Create Tag dialog, assign a unique Tag Name as the key (see Tag Restrictions). Optionally, you can restrict the new Tag to a set of Allowed Values before you click SUBMIT.
Restricting Allowed Values
To restrict the values that users can apply to a Tag, simply type your approved values into the Allowed Values field. Press Tab or Enter after each entry.
After you click SUBMIT to create the Tag, it will appear on the Tags Management page with an R(estricted) icon. Hover over the icon to display the restrictions.
Updating Tag Keys
Users who have the Manage Tag Account permission can update an existing Tag on the Tags Management page, by clicking on that Tag row's More Options ⋮ menu.
This menu provides the following options:
- Click Usage Details to open the same Tag Usage Details modal available by clicking in the Tag Name column.
- Click Edit to open the Edit Tag dialog, where you can add or remove Allowed Values. (You cannot change the Tag Name here.)
- Click Delete to delete the Tag key from Harness. (This also frees up its name for reuse.) You will see the confirmation message box below.