Output variables

As you work with variables in Octopus, there will be times when you want to use dynamic variables, for example, the value of a variable is the result of a calculation, or the output from running a command. For these scenarios, Octopus supports output variables.

Output variables can be set anywhere that Octopus runs scripts - for example, the Script Console, or package scripts and script steps in a deployment. See below for examples of setting output variables in each of the different scripting languages supported by Octopus.

For example, you might have a standalone PowerShell script step called StepA that does something like this:

PowerShell
Set-OctopusVariable -name "TestResult" -value "Passed"
C#
Octopus.SetVariable("TestResult", "Passed");
Bash
set_octopusvariable "TestResult" "Passed"
F#
Octopus.setVariable "TestResult" "Passed"
Python3
set_octopusvariable("TestResult", "Passed")

You can then use the variable from other steps, either in variable binding syntax:

#{Octopus.Action[StepA].Output.TestResult}

Or other scripts:

PowerShell
$TestResult  = $OctopusParameters["Octopus.Action[StepA].Output.TestResult"]
C#
var testResult = Octopus.Parameters["Octopus.Action[StepA].Output.TestResult"]
Bash
testResult=$(get_octopusvariable "Octopus.Action[StepA].Output.TestResult")
F#
let testResult = Octopus.findVariable "Octopus.Action[StepA].Output.TestResult"
Python3
testResult = get_octopusvariable("Octopus.Action[StepA].Output.TestResult")

Sensitive output variables

PowerShell
Set-OctopusVariable -name "Password" -value "correct horse battery staple" -sensitive
C#
Octopus.SetVariable("Password", "correct horse battery staple", true);
Bash
set_octopusvariable "Password" "correct horse battery staple" -sensitive
F#
Octopus.setSensitiveVariable "Password" "correct horse battery staple"
Python3
set_octopusvariable("Password", "correct horse battery staple", True)

System output variables

After a step runs, Octopus captures the output variables, and keeps them for use in subsequent steps. In addition to variables that you create yourself using Set-OctopusVariable, Octopus also makes a number of built-in variables available. Here are some examples of commonly used built-in output variables:

  • For NuGet package steps:
    • Octopus.Action[StepName].Output.Package.InstallationDirectoryPath - the path that the package was deployed to
  • For manual intervention steps:
    • Octopus.Action[StepName].Output.Manual.Notes - notes entered in response to the manual step
    • Octopus.Action[StepName].Output.Manual.ResponsibleUser.Id
    • Octopus.Action[StepName].Output.Manual.ResponsibleUser.Username
    • Octopus.Action[StepName].Output.Manual.ResponsibleUser.DisplayName
    • Octopus.Action[StepName].Output.Manual.ResponsibleUser.EmailAddress

Output from multiple deployment targets

Output variables become more complex when multiple deployment targets are involved, but they can still be used.

Imagine that an output variable was set by a script which ran on two deployment targets (Web01 and Web02) in parallel, and that both set it to a different value. Which value should be used in subsequent steps?

In this scenario, the following output variables would be captured:

NameValueScope
Octopus.Action[StepA].Output[Web01].TestResultPassed
Octopus.Action[StepA].Output[Web02].TestResultFailed
Octopus.Action[StepA].Output.TestResultPassedDeployment Target: Web01
Octopus.Action[StepA].Output.TestResultFailedDeployment Target: Web02
Octopus.Action[StepA].Output.TestResultPassed
Octopus.Action[StepA].Output.TestResultFailed

Note that for each output variable/deployment target combination:

  • A variable is created with the deployment target name contained in the variable name: this allows you to reference output variables from set by one deployment target from another deployment target.
  • A variable is created that is scoped to the deployment target. This way Web01 will always get the value Web01 set, and Web02 will get the value Web02 set.
  • A variable is created with no scope, and no differentiator in the name. When referencing this value, the result will be indeterministic, but it allows scripts to use the value without knowing which deployment target set it.

For some practical examples of using output variables, and how scoping rules are applied, see the following blog posts:

Output from deploy a release steps

Output variables from deployments triggered by a Deploy a Release step are captured and exposed as output variables on the Deploy a Release step.

To get the value of an output variable from a Deploy a Release step, use the Output.Deployment variable on the Deploy a Release step. For example, if your Deploy a Release step is named “Deploy Web Project”, the target step in the child project is named “Update IP Address”, and the variable name is “IPAddress”, you would use the following variable to access it in the parent project: Octopus.Action[Deploy Web Project].Output.Deployment[Update IP Address].IPAddress.

Setting output variables using scripts

You can set output variables using any of the scripting languages supported by Octopus. In each case we make special functions available to your scripts by bootstrapping them with a template defined in the open-source Calamari project.

PowerShell

PowerShell Bootstrapping

From a PowerShell script, you can use the PowerShell CmdLet Set-OctopusVariable to set the name and value of an output variable. The CmdLet takes two parameters:

  • [string]$name - the name you want to give the output variable following the same naming conventions used for input variables.
  • [string]$value - the value you want to give the output variable.

For example:

PowerShell

Set-OctopusVariable -name "TestResult" -value "Passed"

C#

ScriptCS Bootstrapping

From a C# script, you can use the public static void SetVariable(string name, string value) method to set the name and value of an output variable.

C#

Octopus.SetVariable("TestResult", "Passed");

Bash

Bash Bootstrapping

In a Bash script you can use the set_octopusvariable function to set the name and value of an output variable. This function takes two positional parameters with the same purpose as the PowerShell CmdLet.

Bash

set_octopusvariable "TestResult" "Passed"

F#

FSharp Bootstrapping

From a F# script, you can use the setVariable : name:string -> value:string -> unit function to collect artifacts. The function takes two parameters with the same purpose as the PowerShell CmdLet.

F#

Octopus.setVariable "TestResult" "Passed"

Python3

set_octopusvariable("TestResult", "Passed")

Best practice

If you have multiple steps which depend on an output variable created by a previous step in your deployment process, it can be cumbersome to need to use the full variable name everywhere, e.g. Octopus.Action[StepA].Output.TestResult.

A useful pattern is to create a project variable which evaluates to the output variable, e.g.

Variable nameValue
TestResult#{Octopus.Action[StepA].Output.TestResult}

This allows using TestResult as the variable name in dependent steps, rather than the full output variable name. In the case of the step name changing (e.g. StepA -> StepX), this also reduces the amount of places the step name in the output variable expression needs to be changed.

Learn more

Help us continuously improve

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

Send feedback

Page updated on Sunday, January 1, 2023