Target tag set docs

src/pages/docs/infrastructure/deployment-targets/target-tags.mdx

@@ -1,13 +1,14 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-06-27
-modDate: 2024-06-27
+modDate: 2026-02-24
 title: Target tags
 description: Before you can deploy software to your deployment targets, you need to associate them with target tags. This ensures you deploy the right software to the right deployment targets.
 navOrder: 20
 ---
 
 Before you can deploy software to your deployment targets, you need to associate them with target tags. This ensures you deploy the right software to the right deployment targets. Typical target tags include:
+
 - product-cluster
 - web-server
 - app-server
@@ -16,16 +17,19 @@ Before you can deploy software to your deployment targets, you need to associate
 Using target tags means the infrastructure in each of your environments doesn’t need to be identical and the deployment process will know which deployment targets to deploy your software to.
 
 Deployment targets:
+
 - Must have at least one tag
 - Can have multiple tags
 - Can share tags
 
 ## Add target tags \{#create-target-roles}
+
 Target tags are created and saved in the database as soon as you assign them to a deployment target.
 
 Decide on the naming convention you’ll use before creating your first target tag as you can’t change the case after the target tag has been created. For example, you can’t switch from all lowercase to camel case.
 
 To create a target tag:
+
 1. Register a deployment target or click on an already registered deployment target and go to Settings.
 2. In the Target Tags field, enter the target tag you’d like to use (no spaces).
 3. Save the target settings.
@@ -36,5 +40,41 @@ You can check all the target tags assigned to your deployment targets from the *
 
 [Getting Started - Machine Roles](https://www.youtube.com/watch?v=AU8TBEOI-0M)
 
-## Older versions
-**Target roles** are **target tags** from Octopus Deploy 2024.2 onwards. The functionality remains the same. This is only a name change to make our terminology clearer.
+## Target tag sets \{#target-tag-sets}
+
+:::div{.warning}
+Target tag sets are supported from Octopus version **TODO**.
+:::
+
+Target tags are now organized into **target tag sets**, which are [tag sets](/docs/tenants/tag-sets) scoped to deployment targets. This gives you a structured way to group related target tags together, just as you can group tags for tenants, environments, projects, and runbooks.
+
+### The [System] Tag Set \{#system-tag-set}
+
+All existing target tags are automatically migrated into a built-in tag set called **[System] Tag Set**. This set is managed by Octopus and cannot be renamed or deleted.
+
+### Custom target tag sets \{#custom-target-tag-sets}
+
+In addition to the [System] Tag Set, you can create your own target tag sets to organize deployment targets by attributes relevant to your team. For example, you might create a tag set for cloud provider, region, or tier.
+
+To create a custom target tag set:
+
+1. Go to **Deploy ➜ Tag Sets** and click **Add Tag Set**.
+2. Give the tag set a name and select **Target** as the scope.
+3. Choose the tag set type:
+   - **MultiSelect:** Allow multiple tags from this set to be assigned to a target.
+   - **SingleSelect:** Allow only one tag from this set to be assigned to a target.
+4. Add the tags you want to include in the set.
+5. Save the tag set.
+
+Each tag set appears as its own field in the deployment target settings, where you can assign tags from that set to a target.
+
+Learn more about [tag sets](/docs/tenants/tag-sets), including tag set types, scopes, and how to create and manage them.
+
+### API compatibility \{#api-compatibility}
+
+The Octopus REST API represents target tags using a `roles` field on deployment target resources. This field continues to work as before — it returns and accepts the target tag values regardless of which tag set they belong to. No changes are required to existing API integrations.
+
+## Older versions \{#older-versions}
+
+- **Target roles** were renamed to **target tags** in Octopus Deploy 2024.2. The functionality was unchanged. This was only a name change to make our terminology clearer.
+- **Target tags** were migrated to **target tag sets** (with a built-in [System] Tag Set) in Octopus version **TODO**. Existing target tags were moved automatically with no action required.

src/pages/docs/tenants/tag-sets.md

@@ -1,14 +1,14 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2025-10-08
-modDate: 2026-02-05
+modDate: 2026-02-24
 title: Tag sets
 icon: fa-solid fa-tags
 description: Tag sets are a categorizing system that let you add custom metadata to resources in Octopus Deploy.
 navOrder: 35
 ---
 
-Tag sets provide the structure for grouping similar tags together, resulting in more orderly metadata. Currently, tags can be applied to tenants, environments, projects, and runbooks, with support for additional resource types planned for the future.
+Tag sets provide the structure for grouping similar tags together, resulting in more orderly metadata. Currently, tags can be applied to tenants, environments, projects, runbooks, and deployment targets, with support for additional resource types planned for the future.
 
 :::figure
 ![An example set of tenant tags](/docs/img/tenants/images/tag-sets.png)
@@ -34,8 +34,9 @@ Tag sets can be scoped to specific resource types:
 - **Environment**
 - **Project**
 - **Runbook**
+- **Target**
 
-A tag set can be scoped to multiple resource types (Tenant, Environment, Project, and/or Runbook), allowing you to use the same tag set across different resources.
+A tag set can be scoped to multiple resource types, allowing you to use the same tag set across different resources.
 
 ## Managing tag sets {#managing-tag-sets}
 
@@ -93,6 +94,7 @@ You can use canonical names when:
 - **[Environment tags](/docs/infrastructure/environments#environment-tags):** Learn how to use tags to classify environments by attributes like cloud provider, region, or tier.
 - **[Project tags](/docs/projects/setting-up-projects#project-tags):** Learn how to use tags to classify and organize projects.
 - **[Runbook tags](/docs/runbooks#runbook-tags):** Learn how to use tags to organize and filter runbooks with custom metadata.
+- **[Target tag sets](/docs/infrastructure/deployment-targets/target-tags#target-tag-sets):** Learn how to use tag sets to group and assign target tags to deployment targets.
 
 ## Learn more