Tenant variables

Tenant variables allow you to configure variables that can have different values for each tenant/environment combination.

Tenant variables are provided using variable templates which map a single variable name to different values for each tenant. Each variable template can define the data type, name, label, help text, and default value.

There are two types of variable templates:

Project templates are variable values that differ between projects and environments for a tenant. For example, server names or database connection settings.
Common templates are variable values that are common across all tenants but need a unique value per tenant. For example, website names, titles, headers, images, logo, URLs, contact information. These values don’t change across projects and environments for a tenant.

View a working example on our samples instance.

Project templates

Project templates allow you to specify variables that can have different values per tenant/environment combination. A perfect example would be a connection string or a database server. With project templates, you define them at the project level.

From Octopus 2024.1, we’ve improved the multi-tenancy variable management experience. For versions older than 2024.1, see prior to 2024.1

To add a project template:

Navigate to the Tenant Variables page in any project.
Click Add project template.
Add the details to your template and click Add.

	Description	Example
Name	The name of the variable template. This will also be the name given to the resulting variable value you can use in your deployment process.	`Tenant.Alias`
Label	The label that will be displayed when prompting for the variable value.	Tenant alias
Help text	The descriptive help text that will be displayed to provide the user with enough information to accurately provide the value.	A shortened, URL friendly, version of the tenant’s name.
Control type	You can select one of several different data types. This controls the user interface provided to collect the variable value, and determines how the variable value is interpreted. Note the variable values will be stored and interpreted as text.	Single-line text box, multi-line text box, drop down, checkbox, sensitive/password box, Azure account
Default value	The value that will be given to the variable if an actual value is not provided. The default value can contain variable binding expressions.	`https://#{Tenant.Alias}.myapp.com`
Options	(Only applies when control type is drop down). This defines the list of options available for the user to select from the drop down list. Enter each option on a new line. Use `\|` to separate values and display text.	`Value1\|Display text 1` `Value2\|Display text 2`

Values for your newly created templates will be displayed for each tenant/environment combination. If you don’t see any values, make sure you’ve connected tenants to the project. You can filter the displayed values to a specific template by selecting it from the list on the side, or to specific tenants and environments using the provided filter options.

To set the variable value for a tenant/environment, click the Edit (pencil) icon on the right-side of the table row. This will open a dialog where you can update the value, then click Update to save the new value.

Common templates

To specify common variables that can be used across multiple tenants, you’ll need to add a variable template to either an existing or new library variable set. You’ll also need to include the variable set in the project to manage any template values.

From Octopus 2024.1, we’ve improved the multi-tenancy variable management experience. For versions older than 2024.1, see prior to 2024.1

To manage common template values, navigate to the Tenant Variables page in any project and select the Common Templates tab.

The variable management experience for common templates is similar to project templates, however the side list will show included library variable sets and the values will be grouped by variable set.

To edit a variable value, click the Edit icon on the right-side of a table row, update the value, then click Update to save the new value. Since the same library variable set may be included in multiple projects, any change to a tenant’s value will also affect other projects the tenant is connected to.

Which variable templates apply to a tenant

When you connect a tenant to a project, variable templates defined by the project itself, or by included library variable sets, will be required by the tenant.

Library variable templates will be collected once - they are considered to be constant for the tenant. Think of these like “custom fields” for your tenants.
Project variable templates will be collected once for each project/environment combination the tenant is connected to. Think of these like database connection settings for the specific tenant/project/environment combination.

By carefully designing your variable templates you can implement complex multi-tenant deployment scenarios.

Prior to 2024.1

Project templates

To add a project template:

Navigate to the Variables ➜ Project Templates tab in your tenant connected project.
Click ADD TEMPLATE.
Add the details to your template and click ADD:

Then to set the variable values for a tenant:

Navigate to the Variables ➜ Project Variables tab in the tenant screen:
Expand each connected environment and provide values for each project template:

Library variable set templates

To specify common variables that can be used across multiple tenants, you need to add a variable template to either an existing or new library variable set: