About OCL
Octopus Configuration Language (OCL) is based on a subset of Hashicorp Configuration Language (HCL). OCL files use the .ocl file extension, and are located in the base path defined in the projects version control settings.
General information about the OCL format can be found here, including the EBNF notation.
Deployment Process
The Deployment Process is defined in the deployment_process.ocl file. It consists of one or more steps. These steps are defined as blocks in OCL.
step block
Each step contains one label, which is the slug of the step. This must be unique throughout the process.
step "<step-slug>" {
...
}step.name
The name of the step. If omitted, the name will default to the slug.
step.condition
Valid values: Success, Failure, Always, Variable
Default: Success
step.package_requirement
Valid values: LetOctopusDecide, BeforePackageAcquisition, AfterPackageAcquisition
Default: LetOctopusDecide
step.properties
Properties is a dictionary of key-value-pairs. Example:
properties = {
Octopus.Account.Id = "My Awesome Account"
MyCustomProperty = "My Value"
...
}step.start_trigger
Valid values: StartAfterPrevious, StartWithPrevious
Default: StartAfterPrevious
step.action block
Steps generally contain a single action. However, there are some cases where they can contain multiple steps. Actions are also defined as OCL blocks.
action "<action-slug>" {
...
}step.action.action_type
Tells Octopus what type of action this is, e.g: Octopus.Script, Octopus.Nginx, Octopus.AzureWebApp, etc.
step.action.channels
A list of channel slugs which this action will be executed for.
channels = ["default", "pre-release"]step.action.condition
Valid values: Success, Variable
Default: Success
step.action.environments
A list of environment slugs where this action will be executed.
environments = ["production", "staging"]step.action.excluded_environments
A list of environment slugs where this action will be excluded from execution.
excluded_environments = ["production", "staging"]step.action.is_disabled
Valid values: True, False
Default: False
step.action.is_required
Valid values: True, False
Default: False
step.action.notes
This field allows for any custom notes.
step.action.properties
Same as the Step properties.
step.action.step_package_version
step.action.tenant_tags
A list of canonical tenant tag names which this action applies to.
tenant_tags = ["My Tenant/My Tag", "My Tenant/My Other Tag"]step.action.worker_pool
The slug of a worker pool where this action should execute.
worker_pool = "my-worker-pool"step.action.worker_pool_variable
The name of the variable pointing to a worker pool where this action should execute.
worker_pool_variable = "WorkerPoolVariable"step.action.container block
If the action should be executed in a container, the container block can be used to specify the container.
container "<IMAGE_NAME>" {
feed = "<CONTAINER_FEED_SLUG>"
}step.action.package block
Actions can reference packages using one or more package blocks.
packages "<PACKAGE_NAME>" {
acquisition_location = "Server|ExecutionTarget|NotAcquired"
feed = "<FEED_SLUG>"
package_id = "<PACKAGE_ID>"
# Optional properties block, same as above properties
properties = {
<PROPERTY NAME> = "<VALUE>"
}
# Optional: Todo
step_package_inputs_reference_id = "<VALUE>"
}Example
step "Hello world (using PowerShell)" {
action {
action_type = "Octopus.Script"
is_required = true
properties = {
Octopus.Action.RunOnServer = "true"
Octopus.Action.Script.ScriptBody = "Write-Host 'Hello world, using PowerShell'"
Octopus.Action.Script.ScriptSource = "Inline"
Octopus.Action.Script.Syntax = "PowerShell"
}
worker_pool = "raspberry-pi-cluster"
}
}
step "Hello world (using Bash)" {
start_trigger = "StartWithPrevious"
action {
action_type = "Octopus.Script"
is_required = true
properties = {
Octopus.Action.RunOnServer = "true"
Octopus.Action.Script.ScriptBody = <<-EOT
echo 'Hello world, using Bash'
echo 'We also support multi-line scripts!'
EOT
Octopus.Action.Script.ScriptSource = "Inline"
Octopus.Action.Script.Syntax = "Bash"
}
worker_pool = "raspberry-pi-cluster"
}
}Variables
The Variables are defined in the variables.ocl file. Variables are defined as blocks in OCL.
variable block
variable "<LABEL>" {
...
}Each variable block has a label, which is the name of the variable. Although not recommended, there can be multiple variable blocks with the same label value. They will be treated a single variable and the contents of each block will be merged.
The variable block contains one or more value blocks.
variable.value block
value "<VARIABLE_VALUE>" {
...
}variable.value.type
Defines the variable type. If omitted, the type is String (text). Valid values are AzureAccount, GoogleCloudAccount, AmazonWebServicesAccount, Certificate, WorkerPool, Sensitive, and String. Sensitive values should not be stored in the variables.ocl file - they should be stored in the database by using the Octopus Deploy UI instead.
Example
variable "Backup worker pool" {
value "WorkerPools-3" {
type = "WorkerPool"
}
}variable.value.description
Defines a description for a variable. This is often used to more fully describe what the variable does or any important notes about changing its value.
Example
variable "Logging.Level" {
value "Info" {
description = "Valid values are 'Trace', 'Debug', 'Info', 'Warn', 'Error', 'Fatal', and 'Off'."
}
}variable.value.prompt block
The value block can optional contain a prompt block. This allows for values to be set manually during deployment.
Example
variable "VersionNumber" {
value {
prompt {
description = "Use the 'Version Number' spreadsheet to determine the next available version number."
label = "Version Number"
required = true
}
}
}variable.value.prompt.description
Defines a description for the prompt. This is often used to provide additional information to the user about what the value should be.
variable.value.prompt.label
Defines a label that will be displayed to the user when a deployment is created. This is often a ‘humanized’ version of the variable name.
variable.value.prompt.required
Determines whether the value can be left blank when a deployment is done. The value can be true or false. If omitted, the default value is false.
variable.value.action (Scope)
Defines one or more actions (steps) that the value will apply to.
Example
variable "Logging.Level" {
value "Info" {
action = ["set-up", "tear-down"]
}
}variable.value.channel (Scope)
Defines one or more channels that the value will apply to.
Example
variable "Version.Tag" {
value "2022.3" {
channel = ["current", "2022.3"]
}
}variable.value.environment (Scope)
Defines one or more environments that the value will apply to.
variable "API.Key" {
value "20f5cb22-a4f1-493f-a327-a2206f39edd0" {
channel = ["production"]
}
}variable.value.machine (Scope)
Defines one or more machines that the value will apply to.
variable "Server.Label" {
value "Test SQL Server" {
machine = ["AU023SQL0048PS45-1", "AU023SQL0048PS45-2"]
}
}variable.value.role (Scope)
Defines one or more roles that the value will apply to.
Example
variable "Application.Name" {
value "HAL Portal" {
role = ["Hal-WebApp-Portal"]
}
}Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Sunday, January 1, 2023