Exporting and Importing Projects
The Export/Import Projects feature was added in Octopus Deploy 2021.1
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.
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:
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.
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
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 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 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 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 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 events are not exported.
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 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.
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.
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.
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 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 and package cache is limited to
Maximum Database Size for configuration data (e.g. projects, deployment processes and inline scripts) is limited to
Maximum size for any single package is
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:
Need support? We're here to help.