Tenant variables

You often want to define variable values that are different for each tenant. For example:

  • A database server name or connection string
  • A tenant-specific URL
  • Contact details for a tenant

If you were using an untenanted project, you would have previously defined these values in the project itself. With a tenanted project, you can set these values directly on the tenant for any connected projects.

Variable templates

Tenant variable values can be provided in one of two ways:

Both of these methods use the variable templates feature.

Which variable templates apply to each 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.

  1. 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.
  2. 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.

Project variables

Project variables allow you to specify a variable that a tenant can change. A perfect example would be a connection string or a database server. You define project variables using project templates.

You can specify the variable type for the project template, just like regular variables. You can also provide a default value which the tenant can overwrite.

On the tenant variable screen, you can set values for these variables.

The great thing about project template variables is that they are treated like any other variable, and can be used in steps like regular project variables.

Common variables

Common variables are similar to project variables. The main difference between the two is that common variables can be used across multiple projects, and they aren’t scoped to environments. Common variables are defined using library variable set templates

For example, if we wanted to define an abbreviation for the tenant to use in a deployment or runbook, we can configure a variable template for the library set.

To include common variables for a tenant, you must add the library variable set in the tenant connected project.

Just like project variables, common variable values are supplied at the tenant level.

Common variable permissions

When editing common variables for a tenant, a user requires variable editing permission (VariableEdit) for the tenant as well as all projects linked to the tenant.

This can be achieved by scoping a user role to:

  • All projects individually
  • The correct project groups
  • A combination of individual projects and project groups

If you don’t have the necessary permissions, you will receive an error like this:


When you create a release in Octopus we take a snapshot of the deployment process and the current state of the project variables.

However, we don’t take a snapshot of tenant variables. This enables you to add new tenants at any time and deploy to them without creating a new release. This means any changes you make to tenant-variables will take immediate effect.

Help us continuously improve

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

Send feedback

Page updated on Thursday, December 7, 2023