Variables

Last updated

Octopus lets you define variables with values that change based on the scope you've assigned to the variables and the scope of your deployments. For instance, as you define your deployment processes there will be steps in your projects that need different database connection strings (or any number of other parameters, i.e., application settings, web service URLs, etc) depending on the environment you're deploying to.

In this example, you can define a variable with one value (the database connection string for the test database) scoped to the test environment and another value (the database connection string for the production database) scoped to the production environment. Then, when your deployment process runs, it will use the value with the test database connection string when deploying to the test environment, and it will use the value with the production database connection string when deploying to the production environment.

Using variables means you don't need to hardcode any of these values. You define your variables and the values you provide will be used at deployment time, allowing you to create applications and deployments that are agnostic of the target environment.

Creating Hello World Variables

In this example, we'll add a variable to a Hello World project that runs a script to say hello. The project uses a variable to vary the message it displays based on the environment the script is deployed to.

  1. To add a variable to your project, navigate to the Project's Overview page, and click Variables to access the variable editor.
  2. Give the variable a name, for instance, Greeting.
  3. Enter the first value for the variable, for instance, Hello, Test, in the value field.
  4. Define the scope for the value, for instance, by selecting the Test environment.
  5. Click ADD ANOTHER VALUE and enter the second value for the variable, for instance, Hello, Production.
  6. Define the scope for this value, for instance, by selecting the Production environment.

Adding a Variable

  1. Save the variable by clicking SAVE.
  2. In this example, we'll reference this variable from a Run a Script step.
  3. Define your step and in the Script Content section, enter the following PowerShell script into the script editor:

Write-Host ​

  1. Select the variable Greeting from the insert variable tool (#{}) next to the script editor, and click SAVE.

Script with Variable

When a release of the project is deployed, the script step will run with the string Hello, Test on the Test environment, and with the string Hello, Production, on the Production environment

Using Variables in Scripts

Octopus allows you to define variables to parameterize your deployments. These variables, along with some predefined variables, will be available from within your scripts.

All variables are strings
Note that in scripts all Octopus variables are strings even if they look like numbers or other data types. You will need to cast to the appropriate type before using the value if you need something other than a string.

Let's consider an example where we have defined a project variable called MyApp.ConnectionString.

# It's a good idea to copy the value into a local variable to avoid quoting issues
$connectionString = $OctopusParameters["MyApp.ConnectionString"]
Write-Host "Connection string is: $connectionString"
// It's a good idea to copy the value into a local variable to avoid quoting issues
var connectionString = Octopus.Parameters["MyApp.ConnectionString"];
Console.WriteLine("MyApp.ConnectionString: " + connectionString);
# It's a good idea to copy the value into a variable to avoid quoting issues
connectionString=$(get_octopusvariable "MyApp.ConnectionString")
echo "Connection string is: $connectionString"
// It's a good idea to copy the value into a variable to avoid quoting issues

// tryFindVariable : name:string -> string option
let connectionString = Octopus.tryFindVariable "MyApp.ConnectionString"
match connectionString with
    | Some x -> printf "Connection string is: %s" x
    | None -> printf "Connection string not found"
 
// Or one of the simplified versions

// Throws KeyNotFoundException when variable does not exist
// findVariable : name:string -> string
let connectionString = Octopus.findVariable "MyApp.ConnectionString"

// Returns default value when variable does not exist
// findVariableOrDefault : defaultValue:string -> name:string -> string
let connectionString = Octopus.findVariableOrDefault "Default Value" "MyApp.ConnectionString"

To see the F# API available to your F# scripts, take a look at our F# signature file.

Variables in PowerShell Scripts

In PowerShell we have pre-defined some script-scoped variables for you as a convenience. Consider the same example as before, a variable named "MyApp.ConnectionString" will be available as both:

  • $OctopusParameters["MyApp.ConnectionString"]
  • $MyAppConnectionString

In the first form the variable name appears just as they appear in the Octopus web portal, while in the second example special characters have been removed. The first form is the most flexible, but in some cases the second form may be more convenient.

$key variable
We fixed an issue which was causing a collision with variables called $key. You can either rename your variable or update to Octopus 3.3.10 or newer.

Passing Parameters to Scripts

Script parameters are available in Octopus 3.3.21 or newer. You can use script parameters for file-based scripts that are sourced from a package.

Octopus can pass parameters to your custom script files for any of the supported scripting languages. This means you can use existing scripts, or write and test your own parameterized scripts that have no knowledge of Octopus, passing Octopus Variables directly to your scripts as parameters. The Octopus scripting API is still available within the context of your script, meaning you can use a mixture of parameters and other Octopus variables and functions.

Consider this example PowerShell script:

PowerShell script using Octopus Variables

$environment = $OctopusParameters["Octopus.Environment.Name"]
Write-Host "Environment: $environment"

You can parameterize this script making it easier to test outside of Octopus:

PowerShell script using parameters

param (
	[Parameter(Mandatory=$True)]
	[string]$Environment
)
Write-Host "Environment: $Environment"

When you call external scripts (sourced from a file inside a package) you can pass parameters to your script. This means you can write "vanilla" scripts that are unaware of Octopus, and test them in your local development environment.

You can define your parameters in the Script Parameters field using the format expected by your scripting execution environment (see below for examples).

Delimiting string values
Don't forget to correctly delimit your parameters correctly for the scripting engine. In the example above we have surrounded the parameter value in double-quotes to handle cases where the Environment Name has spaces: "#{Octopus.Environment.Name}"

Passing Parameters to PowerShell Scripts

You can pass parameters to PowerShell scripts as if you were calling the script yourself from PowerShell, using positional or named parameters.

Script Parameters in Octopus

-Environment "#{Octopus.Environment.Name}" -StoragePath "#{MyApplication.Storage.Path}"

Usage in PowerShell script

Param (
	[Parameter(Mandatory=$True)]
	[string]$Environment,
	[Parameter(Mandatory=$True)]
	[string]$StoragePath
)
 
Write-Host "$Environment storage path: $StoragePath"

Passing Parameters to C# Scripts

You can pass parameters to C# scripts as described here for the ScriptCS engine. ScriptCS only supports positional parameters.

Script Parameters in Octopus

-- "#{Octopus.Environment.Name}" "#{MyApplication.Storage.Path}"

Usage in C# script

var environment = Env.ScriptArgs[0]
var storagePath = Env.ScriptArgs[1]
Console.WriteLine("{0} storage path: {1}", environment, storagePath);

Passing Parameters to Bash Scripts

You can pass parameters to Bash scripts as described in Bash manual.

Script Parameters in Octopus

"#{Octopus.Environment.Name}" "#{MyApplication.Storage.Path}"

Usage in Bash script

environment="$1"
storagePath="$2"
echo "$environment storage path: $storagePath"

Passing Parameters to F# Scripts

You can pass parameters to FSharp scripts as described in MSDN.

Script Parameters in Octopus

"#{Octopus.Environment.Name}" "#{MyApplication.Storage.Path}"

Usage in F# script

let environment = fsi.CommandLineArgs.[1]
let storagePath = fsi.CommandLineArgs.[2]
printfn "$s storage path: $s" environment storagePath

Variables in Octopus

Variables are an important and useful concept in Octopus, so this section describes different ways in which variables can be used.

Scoping variables Variables can be scoped to different environments, deployment targets, target roles, deployment steps, channels, and tenants which allows you to provide different values for the variables for each scope.
Binding syntax Octopus's binding syntax lets you reference variables throughout Octopus. You can also reference variables from other variables.
Library variable sets Library variable sets let you re-use common variables between projects rather than creating them for every project that needs them.
Prompted variables Sometimes the value of a variable changes for each deployment. You can prompt a user for a variable value when scheduling deployments.
Sensitive variables Octopus can securely store sensitive values, for instance, passwords and API keys.
System variables Many built-in variables are available within Octopus, such as the current environment name.
Output variables Output variables let you programmatically set variables during a deployment, and then use those values in subsequent steps.
Variable templates Variable template are used with projects that are deployed to Multi-tenants and let you define which variables are required by tenants for your projects to be successfully deployed.
Certificate variables Octopus supports a certificate variable type that lets you create a variable with a certificate managed by Octopus as the value.
Variable Substitution Syntax Variable substitutions are a flexible way to adjust configuration based on your variables and the context of your deployment.
AWS Account Variables AWS accounts are included in a project through a project variable of the type Amazon Web Services Account.
Azure Account Variables Azure accounts can be referenced in a project through a project variable of the type Azure Account.