octopus branded bento box filled with sushi

Exporting and importing projects between spaces

Michael Richardson

octopus branded bento box filled with sushi

The 2021 Q2 Octopus Deploy release includes a new feature that makes it possible for projects to be exported and then imported into another space, giving you more control over how you organize your Octopus instance. This also allows you to easily move your on-premises Octopus projects to Octopus Cloud.

During development we referred to this as Project Bento, as the goal was a portable container for your Octopus projects.

Spaces and Octopus Cloud

Octopus 2019.1 introduced Spaces, a way to partition your Octopus Server.

We didn't include the ability to move projects between spaces though, because the functionality was complicated to design and build. The demand for this has been consistently strong, with the feedback being that Spaces was less valuable without a way to partition existing projects into new spaces.

Our Customer Solutions team stepped up to fill the gap with the Space Cloner project, a collection of PowerShell scripts to help with copying between spaces. This was useful in many cases, but there were limitations because it operated via the HTTP API, as opposed to being in-the-box.

Fast-forward two years, and people also want to migrate projects from self-hosted Octopus instances to Octopus Cloud.

The 2021 Q2 release introduces the ability to export and import projects as a fully-supported, in-the-box feature.

Project Export/Import menu

Exporting projects

You can select one or more projects to export, and you need to provide a password to encrypt the exported data, as the export will include sensitive variables.

Export projects page

The export runs as a task, and results in a zip file which can be downloaded.

Importing projects

The zip file can then be imported into another space on the same Octopus Server, a different server, or even an Octopus Cloud instance.

Import projects page

Similar to the export, the import runs as a task (large exports can take some time).

The selected projects are included, along with everything they require:

  • Environments
  • Tenants
  • Variable sets
  • Step templates
  • Accounts
  • Certificates

It's also important to note what's not included:

  • Deployment targets. These will need to be reconfigured in the target space because Tentacles need to be explicitly configured to trust another Octopus Server.
  • Packages. It's common for self-hosted projects to have hundreds of gigabytes of packages. Including these in the export zip would be impractical. In many cases, old packages aren't required, and the build server can simply be pointed at the new Octopus Server. For cases where packages are required, we've provided an example script to demonstrate syncing packages via the Octopus API.

When to use the Project Export/Import feature

This first iteration of the Project Export/Import feature was designed primarily for one-time import/exports of a project. This is useful in the following scenarios:

  • Moving a project from a self-hosted instance to Octopus Cloud.
  • Moving a project between two spaces on the same instance, for example when splitting a space into multiple spaces.

This iteration does not address repeatedly moving a project between spaces, for example to test upgrades or promote a project to a secure, segregated Octopus instance.

These scenarios are different in subtle but significant ways, often requiring different variable values, lifecycles, tenants, etc., to be maintained between the instances. We have laid the foundations with this feature to support these scenarios, and hope to do so in a future release. In the meantime, the migrator utility remains a valid option.


The Project Export/Import feature is available in Octopus Cloud instances now, and is part of the 2021.1 release available from the Downloads page.

The feature is currently an early-access release, and we're very keen to hear your feedback. We hope this makes migrating projects from self-hosted to Octopus Cloud simple and smooth.

Watch the webinar

We host webinars regularly. See the webinars page for past webinars and details about upcoming webinars.

Happy deployments!

Tagged with: Product