Exporting and Importing Projects

The Export/Import Projects feature can export one or more projects into a zip file, which can then be imported into other spaces. The target space may be in a different Octopus Server instance, and projects can be exported and imported between self-hosted and Octopus Cloud instances (see below for some specific considerations when moving a project to Octopus Cloud).

Export/Import features are found in the overflow menu on the Projects page.

When exporting, a password is required to assist with encryption. The password should be treated carefully, as it will be used to decrypt any sensitive values contained within the export when importing the project(s) into Octopus.

The export runs as a task. Once the task is complete, the export zip file is attached as an artifact and available for download.

Scenarios

The current implementation of the Export/Import feature was designed for moving a project between spaces, specifically:

• Moving from a self-hosted instance to an Octopus Cloud instance (or vice-versa)
• Splitting a space containing many projects into multiple spaces

Scenarios this feature was not designed for include:

• Backup/restore. See our recommended approach to disaster-recovery for your Octopus instance.
• Cloning projects within a space. There is an easier way to achieve this.
• Promoting changes between environments on different Octopus instances. See below.

Promoting changes between Octopus instances

There are scenarios where it is desirable to create releases and deploy them to test environments on a development Octopus instance before promoting the changes to another instance. This can be due to reasons including:

• security requirements (e.g. air-gapped environments)
• multi-tenancy (deploying Octopus to customer infrastructure)
• maintaining strict control over the changes made to the production Octopus instance

The export/import feature does not currently support these promotion scenarios. It will not import a project if it already exists in the target space.
The ability to import an existing project will likely be added in a future release.

What is imported

The root of the export/import is a project (or multiple projects). The simple rule-of-thumb is everything the project references is included. Specifically:

• The project (name, settings)
• The deployment process and runbooks
• Project variables
• Channels, and all lifecycles referenced
• Environments (see below for details)
• Tenants connected to the project
• Accounts and certificates used by the project
• Library variable sets included in the project
• Step templates used in the deployment process or runbooks
• Other projects referenced by Deploy Release steps

It is worth explicitly mentioning some things that are not included:

• Packages
• Deployment targets
• Audit logs
• Workers
• Project logos
• Triggers

Shared resources

The Octopus Deploy data-model is a web, not a graph. Some resources are shared between projects (environments, tenants, accounts, step templates, etc), and these shared resources are exported with the project. In general, these shared resources are matched by name when importing; i.e. if there is an existing resource with the same name as one in the source then it will be used, otherwise it will be created. Sometimes the import will need to merge some information on import. Some specific examples are mentioned below.

Environments

Any environments which can be reached via the project will be included in the export. This includes:

• Environments included in any of the project’s lifecycles, except when using the default lifecycle.
• Environments used to scope variables in any library variable sets connected to the project
• Environment restrictions defined on any accounts or certificates referenced by the project

Deployment targets

Deployment targets are not included in the export. They will need to be recreated in the target space. For Tentacle deployment targets (both Windows and Linux), there are specific considerations:

Listening Tentacles must be configured to trust the certificate of the Octopus Server. If you are importing your project into a different Octopus instance, for the new instance to be able to communicate with existing listening Tentacles, the following must be true:

• The Tentacles are accessible by the new Octopus instance (i.e. networking and firewalls must be correctly configured)
• The Tentacles are configured to trust the certificate of the new instance. This can be done using the Tentacle configure command.

An alternative is to create a new Tentacle on the same machine. This gives the option to switch to a polling Tentacle (which may be preferable when migrating a project to Octopus Cloud), and allows having both the original and cloned project deployable for a period of time.

Polling Tentacles can be configured to poll multiple Octopus servers using the register-with command.

Packages

Packages from the built-in feed are not included in the export (this is to avoid extremely large export bundles).

Packages can be copied between spaces via the Octopus API. This PowerShell script does this (please consider the package storage limits when moving packages to Octopus Cloud)

Users

Users are not exported, as they are not directly associated with projects.

Any teams which are referenced by projects (for example via manual intervention steps or email steps) will be created if they do not exist in the target space. These teams will be empty.

Workers

Workers are not included in the export. Worker pools referenced by any steps (or variables) will attempt to match by name on the target, and if a matching pool does not exist then an empty pool will be created.

If moving from a self-hosted to an Octopus Cloud instance, any steps which are configured to Run on Server will be converted to run on the default worker pool on import (Run on server is not supported on Octopus Cloud).

If moving from an Octopus Cloud instance to a self-hosted instance, Dynamic Worker Pools will be converted to static worker pools on import (dynamic worker pools are not supported on self-hosted instances).

Audit logs

Audit events are not exported.

Tenants

All tenants connected to the project will be included in the export.

On import, for any tenants which already exist on the destination the project/environment connections in the export will be merged into the existing tenant.

Library Variable Sets

Library variable sets connected to the project will be exported, including all variables.

When importing, if a library variable set with the same name already exists, the variables will be merged. If a variable in the export doesn’t exist on the destination, it will be created. If a variable with the same name and scopes already exists, the variable on the destination will be left untouched.

Step templates

Step templates used in the project’s deployment or runbook processes will be included in the export.

Projects reference specific versions of a step template. When importing, if a step template with the same name and version already exists on the destination the existing step template version will be used. If the step template already exists, but the imported version is greater than the latest on the destination then the version included in the import will be imported into the destination, effectively incrementing the step template. Existing projects on the destination will initially not be impacted, as they will be referencing a specific version which will remain unchanged, but care should be taken on future updates of the step template version in these projects.

Accounts

Any accounts which can be referenced via the project will be included in the export. This includes:

• Accounts which are the value of the project’s variables
• Accounts which are the value of variables in library variable sets connected to the project
• Accounts referenced directly from deployment process steps

When importing, if an account with the same name already exists on the destination, the existing account will be used.

Certificates

Any certificates which can be referenced via the project will be included in the export. This includes:

• Certificates which are the value of the project’s variables
• Certificates which are the value of variables in library variable sets connected to the project

When importing, if a certificate with the same name already exists on the destination, the existing certificate will be used.

Project logos

The project logo will be available when exporting between spaces on the same instance. If exporting between instances, the logo will have to be re-uploaded.

Triggers

Triggers are also not currently included, and will need to be reconfigured in the destination instance.

Moving to Octopus Cloud

When moving a project from a self-hosted Octopus Server instance to an Octopus Cloud instance, limits apply which should be considered. Specifically:

• Maximum File Storage for artifacts, task logs, packages, package cache, and event exports is limited to 1 TB.
• Maximum Database Size for configuration data (e.g. projects, deployment processes and inline scripts) is limited to 100 GB.
• Maximum size for any single package is 5 GB.
• Retention policies are defaulted to 30 days, but this figure can be changed as required.

There are some caveats around worker pools.

Using the API

You can use the Octopus REST API to export or import Octopus projects.

To find out more take a look at our examples:

• Export projects
• Import projects

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