Deploy a release step

The Deploy a Release step lets you have a project trigger the deployment of a release of another project. This is useful when you are coordinating multiple projects.

Deploy release step card

when you add a Deploy a Release step to your deployment process, you can then select the project which will be deployed.

Deploy release select project

You can add many Deploy a Release steps to your process, if you wish to deploy releases of many projects.

Creating a release

When creating a release of a project containing Deploy a Release steps you can select the release version of each project, similar to the way versions of packages are selected:

Create release with deploy release steps

By default, Octopus will select the latest release based on the creation time of the release, and not the Semantic version. This means Octopus might initially select a release that has a lower version that the latest for a Project.


The Channel used for any Deploy a Release step is automatically determined by the release version of the project you select in the create release screen, since a channel is chosen when a release is created.

It’s possible to choose child releases from specific channels when using the Deploy a Release step using package version rules. Watch our - Ask Octopus Episode: Deployment Channels with Child Projects to see it in action.

Conditional deployment

A Deploy a Release step can be configured to:

  • Deploy Always (default).
  • Deploy if the selected release is not the current release in the environment.
  • Deploy if the selected release has a higher version than the current release in the environment.


Variables can be passed to the deployment triggered by the Deploy a Release step. These will be made available to steps within the child deployment’s process, just like regular project variables. Variables passed in will override existing variables in the child project if the names collide.

Deploy release variables

Output variables

You may wish to capture information from a deployment triggered by a Deploy a Release step, either to be used in the parent process or to be passed to another deployment via another Deploy a Release step.

Any output variables generated by a deployment will be captured as output variables on the Deploy a Release step which triggered the deployment. These can then be used by subsequent steps in the process.

These output variables are captured as variables with the following name pattern:

Octopus.Action[Deploy Release Step Name].Output.Deployment[Child Step Name].VariableName

and for machine-specific output variables:

Octopus.Action[Deploy Release Step Name].Output.Deployment[Child Step Name][Machine Name].VariableName


Deploy Release Step Name: The name of the Deploy a Release step in the parent process.
Child Step Name: The name of the step in the child deployment process which set the output variable.
VariableName: The original name of the output variable. e.g. for Set-OctopusVariable -Name "Foo" -Value "Bar" this would be Foo.
Machine Name: The machine the child process was targeting when the output variable was set.

For example, you have a project Project Voltron which contains a Deploy a Release step named Deploy Red Lion which triggers a deployment of another project Project Red Lion.
Project Red Lion contains a step Echo Paladin which sets an output variable. e.g.

Set-OctopusVariable -Name "Paladin" -Value "Lance"

This variable will be available in subsequent steps of the Project Voltron process via the variable Octopus.Action[Deploy Red Lion].Output.Deployment[Echo Paladin].Paladin.


The Lifecycles of projects being deployed by a Deploy a Release step must be compatible with the coordinating project.

For example, if you have two projects, Project A and Project B which are referenced by Deploy a Release steps in another project Project Alphabet. When deploying Project Alphabet to the Test environment, the release versions chosen for Project A and Project B must also be eligible to be deployed to the Test environment according to the lifecycles of those projects.

Multi-tenant deployments

When a tenanted project is being deployed by Deploy a Release step, then the parent project should also be created as tenanted.

When triggering a tenanted deployment of the parent project, the tenant will be used to trigger the child deployment.

If the child project is untenanted, and the parent project is deployed with a tenant selected, then the untenanted child project will simply be deployed, ignoring the tenant.

Deploying a combination of tenanted and untenanted projects

A project can contain multiple Deploy a Release steps which deploy a combination of tenanted and untenanted projects. There are a number of approaches which can be used to control which Deploy a Release steps will be executed.

  • Scope the Deploy a Release step to one or more tenants. This is useful if the child project should only be deployed for particular tenants.
  • If the child project is untenanted, and should only be deployed once for all tenants, then the Deployment Conditions can be used to specify that is should only be deployed if the version does not match. This will prevent it from being deployed multiple times if multiple tenanted-deployments of the parent project are created.

Rolling deployments

Deploy a Release steps may be added as child steps, to be used in a rolling deployment.

When executing a rolling deployment containing a Deploy a Release step, child deployments will be created per deployment target, as each target is rolled over. i.e. if the rolling step specifies a target role which matches 10 deployment targets, then 10 child deployments will be created.

When configuring a Deploy a Release step as a child step in a rolling deployment, the deployment condition should be set to Deploy Always.
Otherwise, as the step rolls across multiple machines, it will see the current release as having already been deployed to the environment, and execution will be skipped.

Canceling a deployment

Canceling the deployment of the parent project as it’s executing the Deploy a Release step won’t cancel the deployment of the child project. The child deployment will continue to completion.

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