How to export your data from Octopus Deploy

How to export data from Octopus Deploy without losing deployment logic

Deployment processes can be exported from Octopus as code, but some of your data stays in the Octopus database unless you extract it deliberately. Projects and their deployment process steps can be stored as Octopus Configuration Language (OCL) files in Git through Config as Code, which gives you a reviewable, versioned copy of the logic. Sensitive variable values, tenant records and release history sit in the database and need a separate plan. A renewal, a price change or a data residency requirement is usually what pushes teams to move, so start by splitting your estate into these two groups before any conversion work. That inventory sets the scope for everything that follows.

The database group needs the most attention. Sensitive variables are the item most likely to block a move, because their values are meant to stay protected and should not be copied into a new repository in plain text. Plan to move them into the secrets store your target platform uses, such as an external secrets manager or Kubernetes Secrets managed by your platform team, and record which owner must supply each value. Tenant records need their own mapping of each tenant to projects, environments and variable scopes. Release history is useful for audit, so decide early whether you need a dated export of past releases and deployments as compliance evidence, and who will keep it.

Before you commit to a timeline, confirm the details with Octopus. Check the Octopus documentation for your server version to learn which Config as Code version and export behavior apply, which resource types it covers, and what limits it has, such as items that must be recreated by hand or values that cannot be read back. Ask your Octopus account contact to confirm the same points in writing, since these details change between releases. Then run a test export in a non-production space, compare the OCL against the live process, and record every difference as an item for the migration backlog.

What you can export from Octopus Deploy and how

This table lists each Octopus data type, the documented way to export it, the output format, and the limits to check before migrating. Treat rows marked for confirmation as a checklist to verify against the Octopus documentation for the version you run. The main takeaway is that Config as Code covers most deployment definitions, while secrets, tenant detail and run history need their own export path.

Data type	Export method	Output format	Known limits
Projects and deployment process	Config as Code (OCL) stored in Git	OCL files in a Git repository	Confirm which step and project features your version exports
Variables (non-sensitive)	Config as Code (OCL) or API	OCL definitions or JSON	Confirm how variable scoping to environments and tenants is exported
Environments	Config as Code (OCL) or API	OCL definitions or JSON	Confirm whether machine assignments travel with environments
Lifecycles	Config as Code (OCL) or API	OCL definitions or JSON	Confirm phase, retention and approval settings in your version
Channels	Config as Code (OCL) or API	OCL definitions or JSON	Confirm version rules and channel-to-lifecycle links export fully
Feeds	API	JSON	Feed credentials are secrets; confirm whether passwords are returned
Machine policies	API	JSON	Confirm whether this object is included in your OCL export
Tenants and tenant tags	API	JSON	Confirm that tenant variables and project connections are included
Release and deployment history	API	JSON, one record per release or deployment	Confirm paging, retention and maximum records per request

What Octopus Deploy does not export and how to handle each gap

Config as Code captures deployment processes, but several things stay in the Octopus database or cannot be read back once set. Each gap below needs a named owner and a replacement before the export is treated as complete.

Sensitive variable values

Sensitive variables are stored encrypted in the Octopus database, and the export carries their names and scoping but not their values. Plan to re-enter each value into a secrets store such as Vault or a sealed secrets controller, then reference it from the Helm, Kustomize or Jenkinsfile definition by name. Many CI platforms also do not let secret values be read back once set, so the practical step is to rotate, not copy. Confirm with your own team which values are still live before cutover.

Target credentials and certificates

Machine connections, Kubernetes cluster credentials, certificates and service account keys used by deployment targets are not part of the process definition. Re-issue these for the new tooling rather than trying to extract them from Octopus. Give Argo CD, Flux or Jenkins their own identities with the narrowest permissions the deployment needs, and retire the Octopus-issued credentials once the first target is migrated and verified.

Tenant and scoping data

Tenants, tenant tags and the variable scoping that links them to environments and projects are configuration held in the Octopus database. Config as Code covers projects and process definitions, so tenant assignments need to be rebuilt as per-tenant values files, overlays or ApplicationSet generators. Record each tenant's environment mapping in a spreadsheet or repository before you begin, because the export will not list it for you.

Release and deployment history

Release records, deployment logs and the audit trail of who approved what live in the Octopus database and are not part of the process export. Git history will preserve the manifests but not the approvals or the timing of each deployment. Archive release and deployment records to an external store such as an object bucket or log platform, and keep the retention period your auditors expect. Confirm the retention setting in your Octopus instance before you plan the archive.

Runbooks and scheduled operations

Runbooks, scheduled triggers and maintenance tasks are separate from deployment processes and may not appear in the project export you version-control. Inventory every runbook and trigger, decide whether each one moves to Jenkins jobs, Kubernetes jobs or another automation tool, and confirm that the owner and approval steps are recreated. Missing a runbook often surfaces only during an incident, so list them before the cutover.

Octopus server configuration and users

Server settings, user accounts, teams, roles and API keys sit in the Octopus instance rather than in project definitions. Recreate access control in the new platform, such as Argo CD RBAC or Jenkins authorization, and bind it to your identity provider. Argo CD, for example, now applies update and delete RBAC only to the application itself, so permissions need to be written against that model, not copied from Octopus roles.

Why sensitive variables and tenant data need their own migration path

A deployment tool holds credentials for every target it can reach, so the export plan has to split the work in two. Process definitions, step templates, project structure and non-sensitive variables can be written out as OCL and committed to Git, where they get reviews and history. Sensitive variable values cannot be treated the same way. Octopus stores them in its database and does not give them back in readable form through an export, so the values have to be re-entered or re-issued from their original sources. Before the first export, list every sensitive variable, the target it unlocks and the owner who can issue a replacement credential. Plan to move those values through a secrets manager with a rotation schedule, and treat each old value as compromised for planning purposes until it has been rotated.

Tenant data needs the same care because tenant tags and tenant-scoped variables decide which values reach which environment. Map each tenant to the environments and tags it uses, then record which variables differ per tenant. In a Kubernetes target, these usually become Helm values files or Kustomize overlays per environment, with non-secret differences in Git and secret references pointing to the secrets store. Confirm the tenant-to-environment mapping with the people who own each customer or business unit, because a missed tag can send a value to the wrong place. Confirm also who approves the new secret store, who holds its admin role, how access is granted per environment, and how access logs are kept. Those approvals should be recorded before any production value is moved, since the new store becomes the place where those credentials now live.

Converting exported processes into Helm, Kustomize or Jenkinsfile definitions

Helm fits Kubernetes deployments where each application is packaged as a chart. Octopus steps that apply manifests or run Helm upgrades map to templates in the chart's templates/ directory, while variables and environment scoping map to values files such as values-staging.yaml and values-production.yaml. Keep one chart per application and one values file per environment, so the diff between environments is visible in Git.

Variables to values: Project and environment variables become entries in values files. Confirm which values are secrets, because those should not be written into plain values files.
Steps to templates: Deploy steps that render Kubernetes resources become template files. Conditional logic in Octopus scripts usually needs to be rewritten as template conditionals.
Scoping to files: Variables scoped to an environment or tenant need a values file or an overlay per target, and scopes that combine several dimensions can produce many files.
Script steps: Custom PowerShell or Bash steps that call external systems are not converted automatically and need a separate review.
Secrets: Sensitive variables stay out of the export, so references to a secrets store must be added by hand.

Before relying on the chart, confirm the Argo CD version you run. Argo CD 3.0 and later define repositories as Kubernetes Secrets, not in the argocd-cm ConfigMap, so the Git source for the chart must be registered that way.

Kustomize keeps plain Kubernetes manifests and layers changes on top of them. A base directory holds the shared resources, and an overlays directory per environment holds the patches, image tags and replica counts that differ. This suits teams that want readable YAML without templating, and Argo CD can read a Kustomize directory directly from Git.

Base from steps: Resources that every environment shares move into base/, along with the manifests that the Octopus deploy steps produced.
Overlays from scoping: Each environment or tenant gets a folder under overlays/ that contains a kustomization.yaml and patches for the values that differ.
Variables to patches: Variables that change image tags or replica counts become images and replicas entries, while other values need strategic merge or JSON patches.
Limits of conversion: Logic such as conditionals, loops or computed values has no direct equivalent in Kustomize and must be redesigned or moved into the build pipeline.
Promotion: Octopus lifecycles do not carry over. Promotion becomes a Git change, such as a pull request that updates an overlay, followed by an Argo CD sync.

Check how many distinct overlays the export implies, and confirm with the team which environment-specific values are secrets that should be referenced from a secrets store instead of committed.

A Jenkinsfile suits server deployments and mixed pipelines, where the work runs on Jenkins agents instead of inside a cluster. Jenkins Pipeline defines builds as code in a Jenkinsfile committed to the project's source control repository, written in Declarative or Scripted syntax made of stages and steps. Octopus process steps become stages, and their scripts become step blocks that run on a labeled agent.

Steps to stages: Each Octopus step maps to a stage in a Declarative pipeline, and the order of stages reflects the process order from the export.
Variables to environment: Project variables map to an environment block or to parameters, and sensitive values should use Jenkins credentials bindings rather than plain text.
Environment scoping: Octopus environments usually become separate stages or branch-based deployments, and approvals become input steps.
Controller settings: The Jenkins Configuration as Code plugin reads YAML from the file named by CASC_JENKINS_CONFIG (default $JENKINS_HOME/jenkins.yaml). It does not install plugins, so plugins must be declared in the Docker image or the Helm chart.
Agents and tooling: Octopus Tentacle targets have no direct equivalent, so agent labels and SSH or Kubernetes agent configuration must be planned separately.

Confirm which Jenkins LTS line you will run and that every plugin your Jenkinsfile depends on is installed, because plugins bundled in older releases may need explicit installation.

Export sequence for a complete Octopus Deploy migration

This sequence moves Octopus projects, variables, tenants and history out of the database and into version-controlled files and archives, so the target platform can be verified against the same deployable state before any production cutover. Each step ends with a check you can record as evidence.

Freeze changes and back up the Octopus database
The Octopus administrator announces a change freeze for projects, variables, lifecycles and tenants, then takes a full backup of the Octopus database and the Octopus Server configuration, including the master key needed to read encrypted values. Store the backup in a restricted location that the migration team can reach. The step is done when a restore of that backup has been tested on a separate SQL Server instance and the restored instance shows the same project and release counts as production. Confirm the master key handling with your own Octopus administrator, since losing it leaves encrypted data unreadable.
Inventory projects, environments, lifecycles, tenants and feeds
The platform owner lists every project, environment, lifecycle, tenant, feed, machine and channel in Octopus, using the Octopus web portal or API, and records each object with its owner and whether it is still in use. Mark objects that have had no deployments for a long period as candidates for retirement rather than migration. The output is a spreadsheet or YAML inventory that becomes the baseline for every later count check. Confirm that the inventory covers all spaces if your instance uses more than one.
Export projects as OCL and commit them to Git
Enable Config as Code for each space and project so that deployment processes, variables, channels and lifecycles are written as Octopus Configuration Language (OCL) files, then commit them to a dedicated Git repository with one folder per project. Review the first export for steps that reference machine names, feed IDs or environment IDs that will need to change in the target. The check is a diff of object counts between the inventory from the previous step and the number of projects, steps and variables in the exported files. Any gap means an object was not exported and needs a manual review.
Extract sensitive variables for rotation
The security team pulls the list of sensitive variables, certificates and account credentials from Octopus, since Config as Code does not carry their values into Git. For each item, record the owning application, the target environments and the system that issued the secret. Plan rotation for every credential that the new platform will read, and store the replacement values in the chosen secrets store rather than in Git. The check is a signed list in which every sensitive item is marked as rotated, migrated or retired, with no item left unassigned.
Archive release and deployment history
The release manager exports release records, deployment logs, task logs and audit events for the retention window your organization requires, using the Octopus API or a database query under change control, and stores them in a read-only archive. Keep the archive separate from the new delivery platform, because Argo CD, Flux or Jenkins will not reproduce Octopus release history. The check is a record count per project that matches the count reported by Octopus for the same window, and a sample of archived logs opens without errors.
Convert steps into the chosen target definitions
The platform engineers map each exported Octopus step to the target format, such as Helm charts or Kustomize overlays for Argo CD or Flux, or a Jenkinsfile for server deployments, and replace lifecycles with Git branch or tag promotion. Parameterize the values that differ by environment and point secret references at the secrets store. Commit the converted definitions in pull requests so each change has a reviewer. The check is that every exported step has a mapped counterpart in the target, recorded in a traceability table that the reviewers have signed off.
Run a parallel deployment to a non-production environment
The delivery team runs the new pipeline against a non-production environment while Octopus continues to deploy to its own targets, and compares outcomes for the same release. Run a dry-run or sync preview first to confirm that the new pipeline deploys the same image tags and configuration values that Octopus would deploy. Then run a full deployment and check health, logs and rollback behavior. The step is complete when the parallel results match for an agreed set of releases and the rollback test has been performed and documented. Only then should the production cutover plan be approved.

How to verify the export is complete before you cut over

Do not treat the export as finished until you can prove it is complete without opening the Octopus web portal. Build a written inventory from the Octopus side, covering every project, deployment process step, variable set, environment, lifecycle, channel and target, and check each item against the files in your Git repository. Count the items per category, then match names and identifiers one by one. A count match alone hides renamed or dropped steps, so compare the step order and the variable scope for each environment as well. Record any item that has no file counterpart as an open defect, and treat sensitive variables and tenants as a separate line item because their values usually live in the database, not in the exported OCL.

Then prove the definitions behave the same way. Run the same release through the old Octopus process and the new Helm, Kustomize or Jenkinsfile pipeline in a staging environment, and compare the rendered manifests, the deployed images and the health checks for each environment. Next, test rollback from the new definitions alone: deploy a known good version, promote a change, and revert through Git or the pipeline tool. Note any step that depends on a secret you have not yet moved to a secrets store, because that dependency will fail at cut over. Assign a named owner to each category (projects and steps, variables and secrets, tenants, release history and targets) who signs off in writing, so no category is accepted by default.

Keep the database backup from the Octopus Server under access control, with a restricted group, logged access and encryption at rest, until the retention period in your policy ends. The backup holds sensitive variable values and deployment history, so it carries the same exposure as the secrets it contains. Confirm final record retention requirements, including how long deployment logs and release records must be kept, with your compliance team before you schedule deletion, and confirm with your legal and security owners how any retained backup will be stored and eventually destroyed.

What to plan before the Octopus Deploy contract renewal or termination

Renewal and termination dates set the pace for everything in an Octopus export. The cards below cover the decisions that have to be made before the contract ends, from rehearsing the export to keeping release history and budgeting for the Git and CI or GitOps platform that will run the new definitions. Confirm every notice period and term with your vendor in writing.

Rehearse the export before notice dates

Run a full export of projects, process steps and variables into a scratch Git repository well before any notice deadline in your contract. Record the date of each run and compare the output with the live deployment process, including environments, channels and lifecycles that the export may not cover. Find gaps while you still have time to fix them and the vendor still has a working system to compare against.

Keep read-only access during transition

Ask for a read-only Octopus account, or a restorable database backup, that stays available until every project has been cut over and verified. Engineers will return to the old process when a new Helm chart or Jenkinsfile behaves differently in production. Confirm with the vendor what access remains after the subscription ends and how long any backup stays retrievable.

Get export and deletion terms in writing

Ask the vendor in writing what data you may export, in which formats, whether the export of sensitive variables is possible, and how and when your tenant data is deleted after termination. Request confirmation of the deletion timeline and any backups the vendor keeps. Treat the answers as contract terms to be reviewed by your legal and procurement teams, not as assumptions.

Schedule the secrets rotation window

Sensitive variables in Octopus are generally not exported as readable values, so you will need to recreate them in a secrets store and rotate the credentials behind them. Plan this as a dated window with owners for each environment, rollback steps and a freeze on unrelated changes. Coordinate with teams that depend on the same accounts, since a rotation that misses one target breaks deployments.

Decide what happens to release history

Release records, deployment logs and approval history may be needed by auditors or incident reviews long after the contract ends. Decide which records to export, in what form, and where they will be stored with access controls and retention that match your policy. Ask your compliance lead to confirm which evidence must survive the transition before you configure the new system.

Budget for Git hosting and GitOps

The new definitions need a Git repository, a CI system to build artifacts and a delivery engine such as Argo CD, Flux or Jenkins to apply them. Budget for each component separately: the hosting platform, the runner or controller capacity, the cluster resources and the people who operate them. Ask each vendor or project what licenses, support and runner charges apply, and ask your implementation partner for a quote tied to a written scope.

How long does an Octopus Deploy export take and what does it need from our team?

What makes an Octopus Deploy export take longer or shorter?

The effort follows the size and shape of your Octopus instance, not a fixed duration. The main drivers are the number of projects, how many of them have custom steps or script modules, how many tenants and tenant-specific variables you run, and how many sensitive variables need a new home. Projects that share a standard deployment template are quick to review. Projects with hand-written PowerShell, bespoke variable scoping or per-tenant overrides take the most time to check. Ask for an inventory of projects, tenants, environments and variable sets before scoping, because that inventory sets the work more than any single figure.

Can our own engineers do the Octopus Deploy export without outside help?

Often yes, for a small estate with a single team that already knows the deployment processes. Your team needs someone who can read Octopus projects, understand each step and export them with Config as Code, then review the resulting files in Git. The harder part is deciding what each step means in the target tool, such as Helm values, Kustomize overlays or a Jenkinsfile stage, and validating that the new definitions produce the same result. Teams with many tenants or many legacy steps usually find that the review and cutover work is where internal capacity runs short.

What does the export need from security and platform teams?

Security staff need to decide where sensitive variables and certificates will live before any definitions are written, since Config as Code does not carry their values. Platform staff need to confirm the target clusters, namespaces, Git repository layout and the access model for the new pipelines. Both teams should review who can read the exported repository, because process definitions often reveal hostnames, account names and internal conventions. Confirm the exact export behavior and any required permissions for your Octopus version with your own Octopus administrator and the vendor documentation.

What happens to our Octopus release history during the export?

Config as Code exports deployment process and configuration, not the full history of releases and deployments. Release records, deployment logs and task history stay in the Octopus database. Decide early whether you need that history for audit or incident review, and how long you must keep it. Many teams export the history they need into a report or archive while the database remains available, then retire the instance on a schedule their compliance owner approves. Confirm your retention obligations before you plan the decommissioning date.

Can we use a Config as Code export as is, or does it need rework?

Treat the export as a starting point. The exported OCL files capture projects, process steps and many settings, so they give you a reviewable record in Git. They do not produce working Helm charts, Kustomize bases or Jenkinsfiles by themselves, and they do not supply secret values. Expect to rewrite steps that depend on Octopus-specific variables, feature toggles, custom step templates or agent targets. Each rewritten definition should be tested in a non-production environment against the same inputs before any production traffic moves.

When is it worth scoping outside help for the export?

Outside help is worth scoping when the estate has many tenants, a large number of custom steps, sensitive variables spread across scopes, or deployments that must meet audit evidence requirements during the change. It is also worth considering when your team cannot spare people to review and test the output. A fixed-scope engagement works well when the inventory, deliverables and acceptance tests are written down before work starts. DeployOpen plans, implements and documents self-hosted platforms in your own infrastructure and prepares evidence for compliance assessments, but it does not issue audit reports. Ask for a written quote based on your inventory.

How DeployOpen scopes and delivers an Octopus Deploy exit

DeployOpen plans, implements and hands over self-hosted open-source platforms inside your own infrastructure, and an export from Octopus Deploy is scoped the same way. We start from a written scope that defines which projects, processes and variables move, then build and document the target definitions in your repositories.

How we scope

Inventory of projects, environments, machines and tenants that the export must cover
Written list of what moves to Git as OCL and what stays in the Octopus database
Agreed decisions on sensitive variables, release history and where secrets will live

How we build

Config as Code export of deployment processes into version-controlled OCL files
Conversion of steps and variables into Helm, Kustomize or Jenkinsfile definitions per environment
Test runs against non-production targets to compare results with the original Octopus releases

How we hand over

Documentation of the mapping from each Octopus process to its replacement definition
Runbook for re-creating secrets in your chosen secrets store, with no values copied from Octopus
Handover session with your platform and release engineers covering the repository layout

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover
Changes to the export or target definitions are handled under a new written scope
Confirm retainer terms, response expectations and included services with DeployOpen in writing