Variables
As you promote your application through test, UAT, staging and production, there are going to be differences in:
- Database connection strings
- Application settings
- Web service URL's
- ...and many other parameters
To make it easy to support different environments without hard-coding these configuration values, the Octopus web portal allows you to create variables.
These variables are used during your application deployment. For example, variables you define will be automatically substituted into XML configuration files, and made available to your PowerShell scripts. This allows you to create applications and deployment scripts that are agnostic of the target environment.
Escaping
Note that the value of a variable should be the unescaped version. Quotes and other characters that would normally need to be escaped in XML should not be escaped in the Octopus UI. This is because they will be escaped when injected, and doing so could result in double escaping.
Scoping
A variable can be "scoped" to zero or one of each of the following:
- An environment (most common)
- A specific machine
- A specific package
For example, suppose these variables exist:
| Name | Value | Environment | Machine | Package |
|---|---|---|---|---|
| LogLevel | Info | |||
| LogLevel | Warn | Production | ||
| DBConnectionString | Server=SQL-UAT1;Database=... | UAT | ||
| DBConnectionString | Server=SQL-PROD;Database=... | Production |
During deployment, Octopus will try to select the most specifically scoped variable that applies. For example, when deploying to Production, the LogLevelproperty would be Warn. But to any other environment, it would fall back to the less-specific variable and have a value of Infoinstead.
Substitutions
You can use the syntax #{Name} to reference a variable named Name from within the value of another variable. For example:
| Name | Value | Environment |
|---|---|---|
| Database | MyDB | |
| Server | DEVSQL | Development |
| Server | PRODSQL | Production |
| ConnectionString | Server=#{Server};Database=#{Database} |
You can learn more about this feature in our blog post.
Predefined variables
Octopus automatically makes a number of common useful variables available during each deployment. All predefined variables have an Octopus prefix. The available predefined variables are:
| Name | Example | Meaning |
|---|---|---|
| OctopusEnvironmentName | Production | The name of the environment that was selected when this deployment was scheduled. |
| OctopusMachineName | ProdServer01 | The name assigned to the machine in the Octopus Environments page in the web portal. May or may not be the hostname of the actual machine. |
| OctopusReleaseNumber | 1.9 | The release number entered when this release was created in the Octopus web portal. |
| OctopusPackageName | AcmeCorp.Web | The name of the NuGet package being deployed. |
| OctopusPackageVersion | 1.9.3 | The version number of the NuGet package. |
| OctopusPackageNameAndVersion | AcmeCorp.Web.1.9.3 | The above two values combined |
| OctopusProjectName | ACME Website | The name of the current project, as defined in the Octopus web portal |
| OctopusTaskId | tasks-157 | An string used to identity the current task in Octopus. You can use this if you need to record something unique about each deployment. |
| OctopusForcePackageRedeployment | True | (May not be provided) If the "Force redeployment" checkbox was selected when this deployment was scheduled, this value will be True. |
| OctopusOriginalPackageDirectoryPath | C:\Apps\Prod\MyApp\1.0.0 | The path that the deployed package was originally extracted to. |
| OctopusProjectWebLink | /projects/foo | Link to the current project |
| OctopusReleaseWebLink | /projects/foo/releases/1.0.0 | Link to the current release |
| OctopusDeploymentWebLink | /projects/foo/releases/1.0.0/deployments/deployment-1 | Link to the current deployment |
The following additional variables don't have a default value, but can be set by you to override Octopus behavior:
| Name | Example | Meaning |
|---|---|---|
| OctopusPackageDirectoryPath | C:\MyApp | A custom path that you can tell Tentacle to extract your package to. If not set, it will have the value that Tentacle extracted the NuGet package to. |
| OctopusPurgePackageDirectoryBeforeCopy | False | If using OctopusPackageDirectoryPath, set this variable to "True" to clean the target directory before copying. |
| OctopusWebSiteName |
MySite or: MySite/MyVDir |
Override the IIS site, or use a forward slash to specify a virtual directory, if you want to customise the site/virtual directory used by the IIS convention. |
| OctopusNotAWebSite | True | Set to "True" to tell Tentacle to skip the IIS convention(i.e., don't configure any IIS sites). |
| OctopusPrintVariables | False | Set to "True" to tell Tentacle to print the value of all variables passed to it. This is off by default in case you have sensitive variables. We recommend only using this setting for non-production environments. |
| OctopusTreatWarningsAsErrors | False | Set to "True" to tell Tentacle to fail when warnings are encountered. |
Precedence rules
Variables are scored in a similar way to CSS rules - you can read more here.