This page lists built-in variables Octopus provides for use in deployment processes, runbooks, and custom scripts.
All Octopus variables are strings, even when the value looks like a number or a boolean.
Release variables
Release-level variables are drawn from the project and release being created, and are available throughout a deployment or runbook run.
Variable
Description
Example
Octopus.Release.Id
The ID of the release.
releases-123
Octopus.Release.Number
The version number of the release.
1.2.3
Octopus.Release.Notes
Release notes associated with the release, in Markdown format.
Fixes bugs 1, 2, and 3
Octopus.Release.Created
The date and time the release was created.
Tuesday, September 10, 1<23> PM
Octopus.Release.CustomFields[name]
The value of a custom field set on the release.
TST-123
Octopus.Release.Channel.Name
The channel name associated with the release.
2.x Feature Branch
Octopus.Release.Previous.Id
The ID of the previous release of the project.
releases-122
Octopus.Release.Previous.Number
The version number of the previous release of the project.
1.2.2
Octopus.Release.PreviousForEnvironment.Id
The ID of the previous release of the project to the current environment.
releases-122
Octopus.Release.PreviousForEnvironment.Number
The version number of the previous release of the project to the current environment.
1.2.2
Octopus.Release.CurrentForEnvironment.Id
The ID of the release of the last successful deployment to the current environment.
releases-122
Octopus.Release.CurrentForEnvironment.Number
The version number of the release of the last successful deployment to the current environment.
1.2.2
Octopus.Release.Git.BranchName
The branch name the release was created from. Available for version-controlled projects.
features/some-new-feature
Octopus.Release.Git.CommitHash
The commit hash the release was created from. Available for version-controlled projects.
0c708f...6eba
Octopus.Release.Git.Ref
The git reference the release was created from. Available for version-controlled projects.
refs/heads/main
Release package and build information variables
These variables expose the build information pushed from your build server for the packages in a release. They’re populated only when build information has been pushed, and they’re available only in project release notes, not in deployment steps. Each variable is a collection; see Variable substitution syntax for how to iterate and index collections.
Variable
Description
Example
Octopus.Release.Package
The packages, with their commits and work items, associated with the release. A collection of package objects.
#{Octopus.Release.Package[Acme.Web].Version}
Octopus.Release.Builds
The build and version-control details associated with the release. A collection of build objects.
#{Octopus.Release.Builds[0].BuildUrl}
Octopus.Release.WorkItems
The distinct work items across all packages in the release. A collection of work item objects.
#{Octopus.Release.WorkItems[0].Id}
Package object properties
Property
Description
Example
PackageId
The ID of the package.
#{package.PackageId}
Version
The version of the package.
#{package.Version}
Commits
The commits associated with the package. A collection.
#{package.Commits[0].CommitId}
WorkItems
The work items associated with the package. A collection.
#{package.WorkItems[0].Id}
Commit properties (release package and build info)
Property
Description
Example
CommitId
The commit ID. When using Git, this is the commit hash.
#{commit.CommitId}
LinkUrl
A link to the commit.
#{commit.LinkUrl}
Comment
The commit message.
#{commit.Comment}
Work item properties (release package and build info)
Property
Description
Example
Id
The work item ID.
#{issue.Id}
LinkUrl
A link to the work item.
#{issue.LinkUrl}
Description
A description of the work item.
#{issue.Description}
Build properties
Property
Description
Example
Packages
A JSON array of the packages created by the build. A collection.
#{build.Packages}
BuildUrl
A link to the CI build.
#{build.BuildUrl}
Branch
The version-control branch associated with the build.
#{build.Branch}
BuildEnvironment
The CI server that ran the build.
#{build.BuildEnvironment}
BuildNumber
The build number associated with the build.
#{build.BuildNumber}
VcsRoot
A link to the version-control repository associated with the build.
#{build.VcsRoot}
VcsType
The type of version control associated with the build.
#{build.VcsType}
VcsCommitNumber
The commit ID associated with the build.
#{build.VcsCommitNumber}
VcsCommitUrl
A link to the commit associated with the build.
#{build.VcsCommitUrl}
Build package properties
Property
Description
Example
PackageId
The ID of the package created by the build.
#{build.Packages[0].PackageId}
Version
The version of the package created by the build.
#{build.Packages[0].Version}
Deployment variables
Deployment-level variables are drawn from the project and release being deployed, and the infrastructure being deployed to.
Variable
Description
Example
Octopus.Acquire.MaxParallelism
The maximum number of packages deployed concurrently to multiple targets. Default: 10.
2
Octopus.Acquire.DeltaCompressionEnabled
Whether delta compression is used when sending packages to targets.
true
Octopus.Deployment.Comments
User-provided comments on the deployment.
Signed off by Alice
Octopus.Deployment.Created
The date and time the deployment was created.
Tuesday, September 10, 1<23> PM
Octopus.Deployment.CreatedBy.DisplayName
The full name of the user who started the deployment.
Alice King
Octopus.Deployment.CreatedBy.EmailAddress
The email address of the user who started the deployment.
alice@example.com
Octopus.Deployment.CreatedBy.Id
The ID of the user who started the deployment.
users-123
Octopus.Deployment.CreatedBy.Username
The username of the user who started the deployment.
alice
Octopus.Deployment.Error
The error or exit code for a failed deployment.
Script returned exit code 123
Octopus.Deployment.ErrorDetail
The error or exit code for a failed deployment, with the Octopus stack trace.
System.IO.FileNotFoundException: file C:\Missing.txt does not exist
Octopus.Deployment.ForcePackageDownload
Whether the package is downloaded fresh from the feed regardless of whether it’s already on the target.
False
Octopus.Deployment.Id
The ID of the deployment.
deployments-123
Octopus.Deployment.Name
The name of the deployment.
Deploy to Production
Octopus.Deployment.PreviousSuccessful.Id
The ID of the previous successful deployment of this project to the target environment.
deployments-122
Octopus.Deployment.Machines
The IDs of the machines targeted by the deployment.
machines-123,machines-124
Octopus.Deployment.SpecificMachines
The specific machines targeted by the deployment, if any.
machines-123,machines-124
Octopus.Deployment.ExcludedMachines
The IDs of machines excluded from the deployment, usually because they were unavailable.
machines-123,machines-124
Octopus.Deployment.Tenant.Id
The ID of the tenant being deployed for. Not present for untenanted deployments.
Tenants-123
Octopus.Deployment.Tenant.Name
The name of the tenant being deployed for. Not present for untenanted deployments.
Acme Corp
Octopus.Deployment.Tenant.Tags
A comma-separated list of the tenant’s tags. Not present for untenanted deployments.
Tenant type/External, Upgrade ring/Early adopter
Octopus.Deployment.Trigger.Id
The ID of the trigger that created the deployment. If several triggers apply, the ID of one of them.
ProjectTriggers-522
Octopus.Deployment.Trigger.Name
The name of the trigger that created the deployment. If several triggers apply, the name of one of them.
Nightly Deploy to Dev
Octopus.Deployment.WorkerLeaseCap
An opt-in cap on how many steps referencing the same package reuse a single worker before another is selected. Disabled by default; set to a number above zero to opt in. Applies to deployments and runbooks.
5
Octopus.Deployment.Targets
The distinct targets being deployed to across all steps. A dictionary of objects with Id and Name properties, keyed on ID.
#{Octopus.Deployment.Targets[machines-123].Name}
Octopus.Endpoint.type.property
Properties describing the endpoint being deployed to.
ftp.example.com
Octopus.Environment.Id
The ID of the environment.
environments-123
Octopus.Environment.MachinesInRole[role]
The machines with the specified target tag being deployed to.
machines-123,machines-124
Octopus.Environment.Name
The name of the environment.
Production
Octopus.Environment.SortOrder
The order applied to the environment on the dashboard and elsewhere.
3
Octopus.Machine.Id
The ID of the machine.
machines-123
Octopus.Machine.Name
The name used to register the machine in Octopus. Not the same as the hostname.
WEBSVR01
Octopus.Machine.Roles
The target tags associated with the machine.
web-server,frontend
Octopus.Machine.Hostname
The host part of the URI used to register the machine. Set only for Listening Tentacles.
192.168.200.100
Octopus.Project.Id
The ID of the project.
projects-123
Octopus.Project.Name
The name of the project.
OctoFx
Octopus.ProjectGroup.Id
The ID of the project group.
project-groups-123
Octopus.ProjectGroup.Name
The name of the project group.
Public Web Properties
Octopus.Space.Id
The ID of the space.
Spaces-1
Octopus.Space.Name
The name of the space.
Dev Space
Octopus.Task.Argument[name]
An argument value provided when the task was created.
deployments-123
Octopus.Task.Id
The ID of the task.
server-tasks-123
Octopus.Task.Name
The name of the task.
Deploy release 1.2.3 to Production
Octopus.Task.QueueTime
The date and time the task should be queued for execution.
Tuesday, September 10, 1<30> PM
Octopus.Task.QueueTimeExpiry
The date and time before which the task must start.
The previous version of the package deployed to the Tentacle.
1.2.2
Octopus.Web.ProjectLink
A path relative to the Octopus Server URL where the project can be viewed.
/app/projects/projects-123
Octopus.Web.ReleaseLink
A path relative to the Octopus Server URL where the release can be viewed.
/app/releases/releases-123
Octopus.Web.DeploymentLink
A path relative to the Octopus Server URL where the deployment can be viewed.
/app/deployment/deployments-123
Deployment change variables
These variables expose the changes included in a deployment, aggregated across the releases being deployed. They’re available only where build information has been pushed and, for work items, an issue tracker integration is enabled. Several are JSON collections; see Variable substitution syntax for how to iterate and index them.
Variable
Description
Example
Octopus.Deployment.Changes
A JSON array of release-change objects, one per release, each with its release notes and build information.
#{Octopus.Deployment.Changes[0].Version}
Octopus.Deployment.WorkItems
A JSON array of the distinct work items across all changes in the deployment.
#{Octopus.Deployment.WorkItems[0].Id}
Octopus.Deployment.PackageBuildInformation
A JSON array of the distinct package build information across all changes in the deployment.
The output of applying the project’s deployment changes template, in Markdown.
#{Octopus.Deployment.ChangesMarkdown}
Release change properties
Property
Description
Example
Version
The release version.
#{change.Version}
ReleaseNotes
The release notes, in Markdown.
#{change.ReleaseNotes}
BuildInformation
The build information for each package in the release. A collection.
#{change.BuildInformation[0].PackageId}
WorkItems
The work items for the release. A collection.
#{change.WorkItems[0].Id}
Commits
The commits for the release. A collection.
#{change.Commits[0].Id}
Package build information properties
Property
Description
Example
PackageId
The ID of the package.
#{info.PackageId}
Version
The version of the package.
#{info.Version}
BuildEnvironment
The CI server that ran the build.
#{info.BuildEnvironment}
BuildNumber
The build number associated with the build.
#{info.BuildNumber}
BuildUrl
A link to the CI build.
#{info.BuildUrl}
Branch
The version-control branch associated with the build.
#{info.Branch}
VcsType
The type of version control associated with the build.
#{info.VcsType}
VcsRoot
A link to the version-control repository.
#{info.VcsRoot}
VcsCommitNumber
The commit ID associated with the build.
#{info.VcsCommitNumber}
VcsCommitUrl
A link to the commit associated with the build.
#{info.VcsCommitUrl}
WorkItems
The work items for the package. A collection.
#{info.WorkItems[0].Id}
Commits
The commits for the package. A collection.
#{info.Commits[0].Id}
Work item properties (deployment change)
Property
Description
Example
Id
The work item ID.
#{workItem.Id}
LinkUrl
A link to the work item.
#{workItem.LinkUrl}
Source
The issue tracker the work item came from.
#{workItem.Source}
Description
A description of the work item.
#{workItem.Description}
Commit properties (deployment change)
Property
Description
Example
Id
The commit ID.
#{commit.Id}
LinkUrl
A link to the commit.
#{commit.LinkUrl}
Comment
The commit message.
#{commit.Comment}
Action variables
Action-level variables are available while an action runs.
You can also read these variables for a different action using indexed notation, for example Octopus.Action[ActionName].IsSkipped. This is useful when writing run conditions that depend on another action’s status.
Variable
Description
Example
Octopus.Action.Container.Image
The name of the container image being deployed.
OctoFx-RateService
Octopus.Action.Id
The ID of the action.
85287bef-fe6c-4eb7-beef-74f5e5a6b5b0
Octopus.Action.IsSkipped
Whether the action was skipped in the current deployment. Can be True or empty.
True
Octopus.Action.Manual.Instructions
The instructions provided for a manual step.
Don’t break anything
Octopus.Action.Manual.ResponsibleTeamIds
The teams responsible for completing a manual step.
teams-123,teams-124
Octopus.Action.MaxParallelism
The maximum number of targets an action runs on concurrently, and the maximum number of steps that run in parallel. Some built-in steps ignore this value. Default: 10.
5
Octopus.Action.Name
The name of the action.
Website
Octopus.Action.Number
The sequence number of the action in the deployment process.
Whether a warning is logged when no files match a glob pattern in Substitute Variables in Files.
False
Package reference variables
When you reference a package in a custom script, that package contributes its own variables, available per package. The examples below assume a package reference named Acme.
Variable
Description
Example
Octopus.Action.Package[Acme].PackageId
The package ID.
Acme
Octopus.Action.Package[Acme].FeedId
The feed ID.
feeds-123
Octopus.Action.Package[Acme].PackageVersion
The version of the package included in the release.
1.4.0
Octopus.Action.Package[Acme].OriginalPath
The location of the package file before any actions are taken.
The directory the package was installed to on a specific target machine. Use this to read the installation directory for a machine other than the one currently running, for example in a run condition.
The URL of the completed Azure cloud service deployment.
http://c9f52d...409f.cloudapp.net/
Step variables
Step-level variables are available while a step runs.
You can also read these variables for a different step using indexed notation, for example Octopus.Step[StepName].Status.Code. This is useful when writing run conditions that depend on another step’s status.
Variable
Description
Example
Octopus.Step.Id
The ID of the step.
80b3ad09-eedf-40d6-9b66-cf97f5c0ffee
Octopus.Step.Name
The name of the step.
Website
Octopus.Step.Number
The number of the step.
2
Octopus.Step.Status.Code
A code describing the current status of the step.
Succeeded
Octopus.Step.Status.Error
A description of the error, if the step failed.
The server could not be contacted
Octopus.Step.Status.ErrorDetail
A full description of the error, if the step failed.
System.Net.SocketException: The server could not be contacted
The status codes returned by Octopus.Step.Status.Code are Pending, Skipped, Abandoned, Canceled, Running, Succeeded, and Failed.
Tracking deployment status
During a deployment or runbook run, Octopus provides variables describing the status of each step and action, including ones other than the one currently running. This lets you reference another step or action’s outcome, for example when writing a run condition.
Where StepName is the name of the step:
Variable
Description
Example
Octopus.Step[StepName].Status.Code
A code describing the status of the step.
Succeeded
Octopus.Step[StepName].Status.Error
A description of the error, if the step failed.
The server could not be contacted
Octopus.Step[StepName].Status.ErrorDetail
A full description of the error, if the step failed.
System.Net.SocketException: The server could not be contacted
Where ActionName is the name of the action:
Variable
Description
Example
Octopus.Action[ActionName].IsSkipped
Whether the action was skipped in the current deployment. Can be True or empty.
True
Octopus.Action[ActionName].TargetRoles
The machine target tags targeted by the action.
web-server,frontend
For the deployment as a whole, see Octopus.Deployment.Error and Octopus.Deployment.ErrorDetail in Deployment variables. These only contain the exit code and Octopus stack trace for the error. Octopus can’t parse the deployment log, so it can only extract exit and error codes, not detailed information on the cause of the failure. Check the logs for full details on why a deployment failed.
Agent variables
Agent-level variables describe the deployment agent or Tentacle the deployment runs on.
Variable
Description
Example
Octopus.Tentacle.Agent.ApplicationDirectoryPath
The directory the agent installs packages under.
C:\Octopus\Tentacle\Apps
Octopus.Tentacle.Agent.InstanceName
The instance name the agent runs under.
Tentacle
Octopus.Tentacle.Agent.ProgramDirectoryPath
The directory containing the agent’s own executables.
C:\Program Files\Octopus Deploy\Tentacle
Octopus.Agent.ProgramDirectoryPath
The directory containing the server’s or Tentacle’s executables, depending on where the step runs.
C:\Program Files\Octopus Deploy\Octopus
Worker pool variables
When a step runs on a worker, these variables are available.
Variable
Description
Example
Octopus.WorkerPool.Id
The ID of the pool.
WorkerPools-1
Octopus.WorkerPool.Name
The name of the pool.
Default Worker Pool
Server variables
Server-level variables describe the Octopus Server the deployment runs on.
Variable
Description
Example
Octopus.Web.BaseUrl
The default URL the server API can be accessed at, based on the server’s listen prefixes. May not be suitable behind a load balancer or reverse proxy.
https://my-octopus
Octopus.Web.ServerUri
The default URL the server portal can be accessed at, as configured in Configuration ➜ Nodes.
https://my-octopus
Runbook variables
These variables are available during a runbook run.
Variable
Description
Example
Octopus.Runbook.Id
The ID of the runbook.
Runbooks-123
Octopus.Runbook.Name
The name of the runbook.
Restore Database
Octopus.RunbookRun.Created
The date and time the runbook was run.
Friday, March 13, 2020 6:23<38> AM
Octopus.RunbookRun.CreatedUtc
The date and time the runbook was run, in UTC.
3/13/20 6:23:38 AM +00:00
Octopus.RunbookRun.Git.BranchName
The branch name, if the run was created from a branch.
branch-abc
Octopus.RunbookRun.Git.CommitHash
The commit hash used to create the run, for a version-controlled runbook.
14677f...a1e9
Octopus.RunbookRun.Git.Ref
The full git ref used to create the run, for a version-controlled runbook.
refs/heads/branch-abc
Octopus.RunbookRun.Git.TagName
The tag name, if the run was created for a tag.
v1.0.234
Octopus.RunbookRun.Id
The ID of the run.
RunbookRuns-123
Octopus.RunbookRun.Name
The name of the run.
Run on Production
Octopus.RunbookSnapshot.Id
The ID of the snapshot being run.
RunbookSnapshots-123
Octopus.RunbookSnapshot.Name
The name of the snapshot.
Snapshot EXAMPLE3
Octopus.RunbookSnapshot.Notes
Notes associated with the snapshot, in Markdown.
Restores the database
Octopus.Web.RunbookSnapshotLink
A path relative to the Octopus Server URL where the runbook snapshot can be viewed.
/app/snapshots/runbookSnapshots-123
Octopus.Web.RunbookRunLink
A path relative to the Octopus Server URL where the runbook run can be viewed.
/app/runs/runbookRuns-123
Kubernetes variables
This variable controls Kubernetes CLI output during Kubernetes deployment actions.
Variable
Description
Example
Octopus.Action.Kubernetes.LogCliOutputAsInfo
Whether successful output from Kubernetes CLI tools (kubectl, helm, aws, az, gcloud) is logged at the Info level instead of Verbose.
True
User-modifiable settings
You define these variables in your project to change how Octopus behaves. Unlike the variables above, you set these values and Octopus reads them.
Variable
Description
Example
Octopus.Acquire.MaxParallelism
The maximum number of NuGet packages downloaded at once when acquiring packages.
3
Octopus.Action.MaxParallelism
The maximum number of targets an action runs on concurrently, and the maximum number of steps that run in parallel. Default: 10.
5
OctopusPrintVariables
Set to True to have Tentacle print the value of all variables passed to it.
True
OctopusPrintEvaluatedVariables
Set to True to have Tentacle print the value of all variables passed to it after evaluation.
True
OctopusSkipFreeDiskSpaceCheck
Set to True to skip the free disk space check when deploying packages.
True
OctopusFreeDiskSpaceOverrideInMegaBytes
The amount of free disk space, in megabytes, to check for, overriding the 500 MB default.
100
OctopusShouldFailDeploymentOnSubstitutionFails
Set to True to fail the deployment if any variable substitution fails.
True
Octopus.Action.PowerShell.CustomPowerShellVersion
The version Windows PowerShell scripts are invoked with (2.0, 3.0, 4.0, 5.0). For PowerShell Core, the value must match a directory in %PROGRAMFILES%\PowerShell.
2.0
OctopusDeleteScriptsOnCleanup
Set to False to keep packaged PreDeploy, Deploy, and PostDeploy scripts in the target directory.
False
Octopus.Action.Script.SuppressEnvironmentLogging
Set to True to suppress script environment-variable logging.
True
Octopus.Action.PowerShell.ExecuteWithoutProfile
Set to True to skip the Tentacle service account’s PowerShell profile when running PowerShell steps.
True
OctopusSuppressDuplicateVariableWarning
Set to True to log the duplicate-variable message as verbose instead of a warning.
True
Octopus.Action.Package.RunScripts
Set to False to prevent scripts inside packages from running.
A file path the Calamari working directory is copied to, including the one-time key used to decrypt sensitive variables.
c:\temp\octopus-debug
Octopus.Deployment.WorkerLeaseCap
An opt-in cap on how many steps referencing the same package reuse a single worker. Disabled by default; set above zero to opt in. Applies to deployments and runbooks.
5
Octopus.Task.ConcurrencyTag
Runs one task at a time per concurrency tag. Set to run tasks in parallel instead of serial, or in serial instead of parallel.