System variables

This page lists built-in variables provided by Octopus that can be used in your deployment custom scripts.

Most of the variables listed here are available in modern versions of Octopus and Calamari. However, some are only available from a specific version. Where this is the case, the version will be noted alongside the variable.

Release

Release-level variables are drawn from the project and release being created.

Release package build information

Octopus.Release.Package details

The Octopus.Release.Package variable is a collection of Package objects based on the following structures:

public class Package
{
  public string PackageId { get; set; }
  public string Version { get; set; }
  public WorkItemLink[] WorkItems { get; set; }
  public Commit[] Commits { get; set; }
}

public class WorkItemLink
{
    public string Id { get; set; }
    public string LinkUrl { get; set; }
    public string Description { get; set; }
}

public class Commit
{
    public string CommitId { get; set; }
    public string LinkUrl { get; set; }
    public string Comment { get; set; }
}

The packages in a release are available as a collection which can be iterated over. e.g.

#{each package in Octopus.Release.Package}
    This release contains #{package.PackageId} #{package.Version}
#{/each}

A particular package can be selected by indexing on the package ID:

#{Octopus.Release.Package[Acme.Web].Version}

The variables available for packages are:

On each package, the commits associated with that package are available as a collection which can be iterated over. e.g.:

#{each package in Octopus.Release.Package}
#{each commit in package.Commits}
- [#{commit.CommitId}](#{commit.LinkUrl}) - #{commit.Comment}
#{/each}
#{/each}

A particular commit can be selected by indexing on the commit ID (when using git the commit ID is the commit hash):

package.Commits[685afd4161d085e6e5f56a66e72e2298e402b114].Comment

The variables available for commits are:

If the Octopus instance has one or more of the Issue Tracker integrations enabled, the commit messages will be parsed for issues. Any issues found will be displayed with the build information, and also available as variables:

#{each issue in package.WorkItems}
- [#{issue.Id}](#{issue.LinkUrl})
#{/each}

A particular issue can be selected by indexing on the ID:

package.WorkItems[4465].LinkUrl

The variables available for issues are:

There is also a distinct list of issues across all packages available in:

#{each workItem in Octopus.Release.WorkItems}
- [#{workItem.Id}](#{workItem.LinkUrl}) - #{workItem.Description}
#{/each}

Octopus.Release.Builds details

The Octopus.Release.Builds variable is a collection of Build objects based on the following structures:

public class Build
{
  public BuildPackage[] Packages { get; set; }
  public string BuildUrl { get; set; }
  public string Branch { get; set; }
  public string BuildEnvironment { get; set; }
  public string BuildNumber { get; set; }
  public string VcsRoot { get; set; }
  public string VcsType { get; set; }
  public string VcsCommitNumber { get; set; }
  public string VcsCommitUrl { get; set; }
}

public class BuildPackage
{
  public string PackageId { get; set; }
  public string Version { get; set; }
}

The builds in a release are available as a collection which can be iterated over. e.g.

#{each build in Octopus.Release.Builds}
    This release contains resources contributed by the build #{build.BuildUrl}
#{/each}

Builds have a zero-based integer index, meaning the first build can be selected at index 0:

Octopus.Release.Builds[0].BuildUrl

The variables available for builds are:

The variables available for build packages are:

Release Branch information

For projects that have version control enabled, information about the branch and commit from which the release was created is also available.

Deployment

Deployment-level variables are drawn from the project and release being deployed.

Deployment changes

The JSON structure contained in the Octopus.Deployment.Changes variables is an array of ReleaseChanges objects matching the following C# classes:

public class ReleaseChanges
{
    public string Version { get; set; }
    public string ReleaseNotes { get; set; }
    public ReleasePackageVersionBuildInformation[] BuildInformation { get; set; }
    public WorkItemLink[] WorkItems { get; set; }
    public CommitDetails[] Commits { get; set; }
}

public class ReleasePackageVersionBuildInformation
{
    public string PackageId { get; set; }
    public string Version { get; set; }
    public string BuildEnvironment { get; set; }
    public string BuildNumber { get; set; }
    public string BuildUrl { get; set; }
    public string Branch { get; set; }
    public string VcsType { get; set; }
    public string VcsRoot { get; set; }
    public string VcsCommitNumber { get; set; }
    public string VcsCommitUrl { get; set; }
    public WorkItemLink[] WorkItems { get; set; }
    public CommitDetails[] Commits { get; set; }
}

public class WorkItemLink
{
    public string Id { get; set; }
    public string LinkUrl { get; set; }
    public string Source { get; set; }
    public string Description { get; set; }
}

public class CommitDetails
{
    public string Id { get; set; }
    public string LinkUrl { get; set; }
    public string Comment { get; set; }
}

There is an entry per release and it includes the release notes (in markdown format) and the build information for each of the packages in that release.

Example: The following iterates the changes in the deployment, printing the release version and the issues contained.

#{each change in Octopus.Deployment.Changes}
    #{change.Version}
    #{each issue in change.WorkItems}
        #{issue.Id} - #{issue.LinkUrl}
    #{/each}
#{/each}

Deployment changes templates

Action

Action-level variables are available during execution of an action. Indexer notion such as Octopus.Action[Website].TargetRoles can be used to refer to values for different actions.

Reference package variables

When referencing packages in custom scripts, they can contribute variables that can be used just like any other variable. The variables are available per package. Assuming a referenced package named Acme:

Azure

Azure Cloud Service

Azure Web Apps

Output

Output variables are collected during execution of a step and made available to subsequent steps using notation such as Octopus.Action[Website].Output[WEBSVR01].Package.InstallationDirectoryPathto refer to values base on the action and machine that produced them. See also Output variables.

Step

Step-level variables are available during execution of a step. Indexer notion such as Octopus.Step[Website].Number can be used to refer to values for different steps.

Agent

Agent-level variables describe the deployment agent or Tentacle on which the deployment is executing.

Worker Pool

When a step is run on a worker, the following variables are available:

Server

Server-level variables describe the Octopus Server on which the deployment is running.

Tracking deployment status

During deployment, Octopus provides variables describing the status of each step.

Where S is the step name, Octopus will set:

Octopus.Step[S].Status.Code
Octopus.Step[S].Status.Error
Octopus.Step[S].Status.ErrorDetail

Status codes include Pending, Skipped, Abandoned, canceled, Running, Succeeded and Failed.

For an action A:

Octopus.Action[A].IsSkipped

For the deployment as a whole:

Octopus.Deployment.Error
Octopus.Deployment.ErrorDetail

Runbook

User-modifiable settings

The following variables can be defined as variables in your project to modify the way Octopus behaves.

Learn more

• Variable blog posts

Help us continuously improve

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

Send feedback

Last updated Sunday, January 1, 2023