Tag sets

Tag sets provide the structure for grouping similar tags together, resulting in more orderly metadata. Currently, tags can be applied to tenants and environments, with support for additional resource types planned for the future.

Tag set types

There are three types of tag sets that can be created:

• MultiSelect: Allows selecting multiple predefined tags from the tag set. This is the standard behavior and works for most scenarios.
• SingleSelect: Allows selecting only one predefined tag from the tag set. Useful when you need to ensure only one option is chosen, such as a cloud provider or deployment tier.
• FreeText: Allows entering custom text values without requiring predefined tags. The tag set name must match exactly, but the tag value can be any arbitrary text. Useful for dynamic values like region identifiers, customer IDs, or version numbers. When using FreeText, only one value per tag set is allowed.

Tag set scopes

Tag sets can be scoped to specific resource types:

• Tenant
• Environment
• Project

A tag set can be scoped to multiple resource types (Tenant, Environment, and/or Project), allowing you to use the same tag set across different resources.

Managing tag sets

Go to Deploy ➜ Tag Sets to create, modify and reorder tag sets and tags.

Design your tag sets carefully

We suggest taking some time to design your tag sets based on how you will apply them to your resources. Our recommendation is to make sure each of your tag sets are orthogonal, like different axes on a chart. This kind of design is important because of how tags are combined when filtering.

Let’s look at example tag sets:

• Importance (VIP, Standard, Trial): concerned with classifying resources so they can be found easily.
• Hosting Region (West US, East US 2): concerned with where resources are hosted or deployed.
• Release Ring (Alpha, Beta, Stable): concerned with when updates are applied.

Grouping tag sets makes it easier for each different class of Octopus user to understand which tags apply to their area, and the impact it will have on their deployments.

Ordering tag sets and tags

Order is important for tag sets, and tags within those tag sets. Octopus will sort tag sets and tags based on the order you define in the library. This allows you to tailor the Octopus user interface to your own situation.

Removing tags

If tags are in use by resources, included in project/runbook release variable snapshots (via project/variable sets), or captured in published runbooks, you will not be able to delete the relevant tag(s) until these associations are removed.

For projects using Config as Code, there are fewer guardrails in place. It’s up to you to take care to avoid deleting any tags required by your deployments. See our core design decisions for more information.

Referencing tags

Tags are referenced using their canonical name which looks like this: Tag Set Name/Tag Name

For example:

• Release Ring/Alpha - References the predefined “Alpha” tag in the “Release Ring” tag set
• Importance/VIP - References the predefined “VIP” tag in the “Importance” tag set
• Region/us-west-2 - For FreeText tag sets, the tag set name “Region” must match exactly, but “us-west-2” can be any arbitrary value

You can use canonical names when:

• Deploying releases using build server integrations or the Octopus CLI.
• Scoping variables to tags.
• Automating Octopus via the Octopus REST API.

Using tags with different resources

• Tenant tags: Learn how to use tags to classify tenants, deploy to multiple tenants, and design multi-tenant deployment processes.
• Environment tags: Learn how to use tags to classify environments by attributes like cloud provider, region, or tier.
• Project tags: Learn how to use tags to classify and organize projects.

Learn more

• Create a tag set via the REST API
• Deployment patterns blog posts

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, October 8, 2025