Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
Tag work items to quickly filter the product backlog or a work item query by categories that you define. A tag corresponds to a one or two keyword phrase that you define. A tag supports your needs to filter a backlog or query, or define a query.
You can add and modify tags from the web portal or from Team Explorer plug-in for Visual Studio. Also, you can open a query in Excel to modify tags in bulk.
Tags are a better choice for filtering work items than using text strings as described in Define a work item query. Tags are a shared resource associated with a project and not a team. If your project contains multiple teams, all teams add to and work from the same set of tags.
Prerequisites
| Category | Requirements |
|---|---|
| Permissions | - To view, follow, and edit work items: View work items in this node and Edit work items in this node permissions set to Allow. By default, the Contributors group has these permissions. For more information, see Set work tracking permissions. - To add tags to work items: Project-level Create new tag definition permission set to Allow. By default, the Contributors group has this permission. |
| Access levels | - Project member. - To add new tags to work items or to view or follow pull requests: At least Basic access. - To view or follow work items: At least Stakeholder access. For more information, see About access levels. - All project members, including members in the Readers group, can send emails containing work items. |
Note
- Provide Stakeholder access to members who want to contribute to the discussion and review progress. These members typically don't contribute to code, but want to view work items, backlogs, boards, and dashboards.
- By default, all Contributors and Stakeholders in public projects can add new and existing tags. In private projects, Stakeholders can only add existing tags. To control the ability to create new tags, set the Create tag definition permission at the project level. For more information, see Change project-level permissions.
Note
- Provide Stakeholder access to members who want to contribute to the discussion and review progress. These are typically members who don't contribute to code, but want to view work items, backlogs, boards, and dashboards.
Add tags to a work item
Tags should be 400 characters or less and not contain separators such as a , (comma), ; (semicolon), or other formatting character.
Recommendation: Don't use the @ character in a tag. Tags that start with the @ character can't be used in a work item query. The @ character signifies a macro within a query and therefore the tag isn't recognized as a tag.
From the web portal, open a work item and add a tag. Choose Add tag and type your keyword. Or, select from the list of previously assigned tags.
To add several tags at one time, type a comma between tags. Tags are case sensitive.
Tags that appear in the tag bar are already assigned to the work item. To unassign a tag, choose the x on the tag, 
.
Bulk add or remove tags
You can bulk update work items to add or remove tags from the web portal. You bulk modify tags in the same way as you bulk modify other fields using the web portal. Or, you can use Excel to bulk add or remove tags.
Note
Boards doesn't support modifying tags in bulk from Visual Studio or other clients.
Query for work items based on tags
To query work items based on tags, add a clause for each tag you want to use to support your query.
Tip
To understand how AND/OR clauses are grouped, see Group clauses. To view the WIQL syntax for a query, install the WIQL query editor extension, which allows you to see the WIQL version of any query editor entry.
You can use the Contains or Does Not Contain operators. Tags that start with the @ character can't be used in a work item query because the query editor interprets the @ character as a macro. For more information, see Define a work item query.
For example, here's a query for all work items that are tagged as either Web or Service.
Note
You can't query for work items that don't have any tags attached to them. If you'd like to up vote the request to support this feature, you can do so on our Developer Community page, Be able to search for empty tags.
Show tags in your backlog or query results
Choose Column Options to add the Tags field to the product backlog or a work item query. If the option doesn't appear, choose More commands 
to select it from the menu of options.
All tags added to the listed work items appear.
Filter lists using tags
From the web portal, you can filter backlogs, boards, and query results using tags.
Begin by choosing Filter 
.
Select the tags that you want to filter on. Keep the OR selection to run a logical OR for all the tags you selected. Or, choose the AND option to run a logical AND on all the selected tags.
Delete, remove, or manage tags
You can't delete tags using the Azure DevOps Web UI.
If you need to remove a tag, create a script or application capable of a delete using the Azure DevOps REST API or the .NET client libraries. For more examples, see Azure-DevOps-Admin-CLI.
Another option is to install the Marketplace Tags Manager, which adds a Tags page under Boards or Work to manage tags, including deletes.
Color-code tags on boards
Highlight tags on board cards by color-coding them. These colors only appear on the board that you configure. They don't appear on backlogs or Taskboards. For more information, see Assign tag colors.
Chart work items and group by tags
You can't group a query-based chart by tags, but, you can group a Chart for Work Items widget by tags that you add to a dashboard. This feature is in public preview. To enable it, see Manage or enable features and turn on Enable group by tags for work item chart widget on dashboard.
To group a Chart for Work Items widget by tags, complete the same steps provided in Add a chart to a dashboard. Make sure that your flat-list query contains Tags in the query clause or as a column option. Then, choose Tags for the Group by selection. To filter the chart to show only some tags, choose the Selected tags radio button and then choose the tags you want the chart to display.
Limits on the number of tags
While no hard limit exists, creating more than 100,000 tags for a project collection can negatively affect performance. Also, the autocomplete dropdown menu for the tag control displays a maximum of 200 tags. When more than 200 tags are defined, begin entering to cause the tag control to display relevant tags.
You can't assign more than 100 tags to a work item or you receive the following message:
TF401243: Failed to save work item because too many new tags were added to the work item.
Save the work item with the tags (100 or less) that you added, and then you can add more tags.
Limit queries to fewer than 25 tags. More than that amount and the query likely times out.
Add tags to the default column view on the product backlog
To add the Tags field as a column field for the product backlog, modify the ProcessConfiguration file to include System.Tags For more information, see the Process configuration XML element reference.
Related content
- Define a work item query
- Customize cards on a board
- Bulk modify work items from the web portal
- Bulk modify work items from Excel