Ephemeral Environments

Ephemeral environments in Octopus Deploy allow to you automatically create test environments on-demand to gain confidence in your changes while helping to keep your infrastructure costs down.

Ephemeral environments integrate smoothly into your existing development workflows by building on existing Octopus features such as Releases, Channels and Runbooks.

Octopus will automatically create and deploy to an ephemeral environment from releases created within a specifically configured channel in a project, and supports provisioning and deprovisioning of associated infrastructure using Runbooks.

Getting started

To configure Ephemeral Environments for your project:

• Select Deploy from the main navigation in the Octopus Web Portal and select your project.
• Select the Ephemeral Environments navigation menu in the sidebar.
• Click the Configure Ephemeral Environments button.
• Follow the configuration wizard to enable the feature for your project.

Parent environment

A parent environment provides scoping of variables, deployment targets and accounts for ephemeral environments. Parent environments are not included in Lifecycles and cannot be deployed to.

Enter the name for a new parent environment or select an existing parent environment then click Next.

Naming

Octopus will automatically provision a new ephemeral environment for you from releases in your project. The name of each environment can be configured using an Environment Name Template. Templates support the same powerful syntax as Variables. Any system variable for a release can be used as part of the template.

Enter a template and click Next.

Custom Fields

Releases support Custom Fields which can be used to configure the name of an ephemeral environment. See Using custom fields in releases for more information.

Examples

Provisioning

Any infrastructure required by an ephemeral environment can be created using a Runbook. Octopus will automatically run this Runbook as needed before deploying a release to the environment.

Create a new runbook, select an existing one or select to skip provisioning and click Next.

Deprovisioning

Any infrastructure used by an ephemeral environment can be removed using a Runbook. Octopus will automatically run this Runbook as needed as part of deprovisioning the environment.

Create a new runbook, select an existing one or select to skip deprovisioning and click Next.

Review and confirm

Review the selected configuration and click Confirm. You can go back and adjust before confirming.

Ephemeral environments are now configured for your project. A new channel has been created in the project which will automatically create and deploy to a new environment for each release.

Click Got it to continue to creating a new environment from a release.

Creating an ephemeral environment

To create an ephemeral environment, create a release in the new channel configured within the project. Octopus will automatically create a new environment and deploy the release to it.

A release can be created using the:

• Octopus Web Portal
• Octopus API
• OctopusDeploy/create-release-action GitHub Action
• Octopus CLI

Provisioning infrastructure

Infrastructure required for an ephemeral environment can be provisioned using a runbook. Octopus will automatically run this runbook before the first deployment to the environment.

• For projects using runbooks stored in Octopus the published snapshot will be used to run the runbook.
• For projects using runbooks stored in version control, the Git reference from the release will be used to run the runbook.

Viewing ephemeral environments

To view ephemeral environments:

• Select Deploy from the main navigation in the Octopus Web Portal and select your project.
• Select the Ephemeral Environments navigation menu in the sidebar.

Environments can be filtered by name and by the current state of the environment for the project.

Updating an existing environment

To update an existing ephemeral environment, create another release that results in the same environment name based on the template. The release will be automatically deployed into the environment.

Deprovisioning an environment

When an ephemeral environment is no longer needed it can be deprovisioned and any infrastructure removed. Octopus will run the selected deprovisioning runbook before (optionally) removing the environment.

• For projects using runbooks stored in Octopus the published snapshot will be used to run the runbook.
• For projects using runbooks stored in version control, the Git reference used to provision the environment will be used to run the runbook.

To deprovision an environment:

• Select Deploy from the main navigation in the Octopus Web Portal and select your project.
• Select the Ephemeral Environments navigation menu in the sidebar.
• Click the menu next to the environment to deprovision and select Deprovision Environment.
• Select whether to keep the environment in Octopus or remove it after deprovisioning.
• Click Deprovision

Automatic deprovisioning of environments

Ephemeral environments can be automatically deprovisioned if they are inactive after after a configurable time period. Deploying a release to an environment or running a runbook against an environment marks the environment as still being active.

To configure automatic deprovisioning of environments:

• Select Deploy from the main navigation in the Octopus Web Portal.
• Select Environments from the sub-navigation.
• Find the parent environment, click the menu and select Edit.
• Edit the Automatic Deprovisioning value.

Changing ephemeral environment settings

To change the ephemeral environment settings for a project:

• Select Deploy from the main navigation in the Octopus Web Portal and select your project.
• Select the Ephemeral Environments navigation menu in the sidebar.
• Select the Settings tab.

Using multiple projects with ephemeral environments

Ephemeral environments can be used by multiple projects in the same way that other environments in Octopus can be used.

Important notes for using multiple projects:

• Each project using the same ephemeral environment must be configured to use the same parent environment.
• Ephemeral environments are shared across a space, and the name must be unique.
• If the environment name created from a release using the template is the same as an existing environment used in another project, a new environment will not be created.
• When deprovisioning an ephemeral environment being used by multiple projects, an option can be selected to deprovision and remove the entire environment, or only deprovision the current project and leave the environment in Octopus.

Release retention

Releases in channels configured for ephemeral environments have a retention policy of 3 days. Releases currently deployed to an ephemeral environment will be kept.

Limitations

The following limitations currently apply to the use of the Ephemeral Environments feature:

• Ephemeral environments cannot be deployed to tenants.
• Parent environments cannot be connected to tenants.
• Ephemeral environments and parent environments cannot be used within lifecycles, deployment freezes and insights reports.
• Ephemeral environments cannot be manually created outside of releases.

Help us continuously improve

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

Send feedback

Page updated on Monday, September 8, 2025