The Export/Import Projects feature was added in Octopus Deploy 2021.1
Version-controlled projects are not currently supported
Migrations can only be performed from an earlier or equal version of Octopus Server. It cannot be used to migrate resources to an older version.
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
- 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
- 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:
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 variable sets connected to the project
- Environment restrictions defined on any accounts or certificates referenced by the project
Environments from the default lifecycle are not exported: If your projects use the default lifecycle that Octopus creates, environments associated with that lifecycle will not be included in the project export. This was an intentional design decision made to avoid some tricky, unexpected behavior during project import.
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.
Variable Sets
Variable sets connected to the project will be exported, including all variables.
When importing, if a 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.
Care should be taken with step templates when exporting/importing projects at different times
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 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 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
Automating the export and import of projects using the REST API as part of a backup/restore process is not recommended. See our supported scenarios.
You can use the Octopus REST API to export or import Octopus projects.
To find out more take a look at our examples:
Help us continuously improve
Please let us know if you have any feedback about this page.
Page updated on Sunday, January 1, 2023