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
- db-server
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
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:
- Register a deployment target or click on an already registered deployment target and go to Settings.
- In the Target Tags field, enter the target tag you’d like to use (no spaces).
- Save the target settings.
The target tag has been created and assigned to the deployment target and can be added to other deployment targets.
You can check all the target tags assigned to your deployment targets from the Infrastructure tab.
Getting Started - Machine Roles
Target tag sets
Target tag sets are supported from Octopus version 2026.2.2344.
Target tags are now organized into target tag sets, which are 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
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
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:
- Go to Deploy ➜ Tag Sets and click Add Tag Set.
- Give the tag set a name and select Target as the scope.
- 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.
- Add the tags you want to include in the set.
- 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, including tag set types, scopes, and how to create and manage them.
Tag validation in deployment steps
When you configure a deployment step, Octopus validates that each target tag referenced by the step exists in a tag set. If a tag does not exist in any tag set, it is displayed with a red ! icon. Hovering over the icon shows a tooltip explaining that the tag does not exist in any tag set, and that you can remove it or recreate it by adding it to a tag set.
This can happen if a tag was deleted from a tag set, or if the step references a tag that was never added to one. To resolve the warning, either:
- Remove the tag from the step and replace it with a valid tag.
- Add the tag to an existing tag set (or create a new one) so it becomes valid.
The warning is informational — it does not prevent you from saving or deploying. However, a tag that doesn’t exist in any tag set won’t match any deployment targets.
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
- 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 2026.2.2344. Existing target tags were moved automatically with no action required.
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Thursday, April 9, 2026