Migrate from Octopus Deploy to Argo CD

Migrate from Octopus Deploy to Argo CD: what moves and what does not

A platform team that runs Kubernetes releases through Octopus Deploy and wants GitOps or tighter cost control should expect the migration to be mostly a change of delivery model. Octopus pushes a release to targets when a person or pipeline triggers it. Argo CD pulls desired state from Git and continuously syncs the cluster to match it. Effort depends less on the number of applications than on three things: how many deployment processes exist, how sensitive the variables are, and how approvals and lifecycles were designed. Platform engineers usually do the core work, with application teams validating their own manifests, because the team that owns each service must agree to where its configuration now lives in Git.

Argo CD is released under the Apache License 2.0 (SPDX: Apache-2.0), and the project itself offers no paid edition, so the software cost is zero. The recurring costs are the Kubernetes clusters it runs on, the people who operate it, and the CI system that builds the artifacts Argo CD deploys. Ask whether your Octopus contract includes machine or tenant add-ons that you will stop paying for, and separately estimate the platform engineering time for Helm or Kustomize work and approval redesign. Argo CD targets Kubernetes only. Windows servers, Linux virtual machines and other non-Kubernetes targets that Octopus reaches through Tentacle or SSH need a separate plan, such as keeping Octopus for those targets or moving them to a different tool, so confirm that inventory before you commit.

Plan the migration in phases rather than as a single cutover. Start with one non-production Kubernetes application, export its process from Octopus using Config as Code, and rebuild each environment as a manifest overlay in Git. Confirm that the argocd-cm and repository definitions match your Argo CD version, since Argo CD 3.0 moved repository configuration into Kubernetes Secrets. Sensitive variables do not export from Octopus in readable form, so each secret must be re-entered in a secrets store and referenced from manifests, and you should rotate any value that was shared through the old system. Finally, decide how promotion works without lifecycles: typically a pull request merge or image tag bump per environment, with approvals enforced by branch protection and required reviews.

Which Octopus capabilities map to Argo CD and which need rework

This table maps the main Octopus Deploy capabilities to their Argo CD equivalents and labels each as clean, needs rework or gap. Read the rows as a planning checklist: clean rows move with little change, rework rows need new manifests or Git structure, and gap rows need a separate tool or process. Confirm current Argo CD features against the official documentation before you commit to a design.

Octopus capability	Argo CD equivalent	Status
Deployment process and steps	Application resources defined as Helm charts or Kustomize overlays in Git, one Application per service per environment	Needs rework: each step must be expressed as declarative manifests, and ordered multi-step logic usually moves into hooks or separate Applications
Variables scoped to environments	Per-environment values files or Kustomize overlays stored in Git	Needs rework: scoped variables become files, and any value that varies by machine must be templated explicitly
Sensitive variables	Encrypted secrets via an external secrets store synced into the cluster, with only references kept in Git	Needs rework: Octopus-held values are not exported, so each secret must be recreated in the chosen secrets store and rotated
Environments and multi-cluster targeting	Git branches or directories per environment, plus ApplicationSets to generate Applications across clusters	Clean: well suited to Kubernetes clusters, with ApplicationSets covering fleets of clusters
Lifecycles and promotion	Git-based promotion through pull requests that update image tags or chart versions in the next environment	Needs rework: promotion order is encoded in Git workflow and automation, not a lifecycle object
Approvals and manual intervention	Pull request reviews, protected branches and sync windows; Octopus-style approval gates have no direct equivalent	Gap: confirm which approval controls your Git host and Argo CD sync windows provide before relying on them
Tenants	Separate namespaces, clusters or Applications per tenant, with tenant-specific values in Git	Needs rework: tenant data models must be redesigned as repository structure and access boundaries
Rollback	Git revert of the manifest change, or syncing an earlier Git revision	Clean: rollback follows Git history, though data migrations are not reversed by Git
Access control and RBAC	Argo CD RBAC policies for projects and Applications, plus Kubernetes RBAC on target clusters	Needs rework: Octopus roles and scopes must be mapped to Argo CD projects and policies
Audit trail	Git commit history for desired state and Argo CD sync and event records	Needs rework: confirm retention of Argo CD logs and events in your own logging stack
Non-Kubernetes targets such as Windows servers and virtual machines	Not covered by Argo CD, which deploys to Kubernetes clusters	Gap: keep Octopus, Jenkins or another tool for these targets

Which exports and integrations to move, and how

Octopus projects can be version-controlled as OCL with Config as Code, but much of the deployment context lives in the database and in the systems around Octopus. Each item below needs a deliberate owner in the Argo CD design, because a missing piece tends to surface only during the first production sync.

Project processes as OCL

Config as Code stores projects, process steps and variables as OCL files that can be reviewed and committed to Git. Use the export as a map of what each project does, then translate each step into a Helm chart, Kustomize overlay or plain manifest in a Git repository that Argo CD watches. Confirm which steps are Kubernetes deployments and which are scripts or runbooks, since scripts do not translate directly.

Sensitive variables must be re-entered

Sensitive variable values are not included in the OCL export. Re-enter each value from a secrets store such as Vault, External Secrets or Sealed Secrets, and reference it from the manifests by name. Plan this as a rotation step as well, because the old values were held by Octopus and should be treated as retired once the new source is live.

Tenants, scopes and release history

Tenants, environment scopes, channels, lifecycles and release history stay in the Octopus database. Tenants become overlays or ApplicationSets per customer or region, lifecycles become Git promotion between branches or directories, and past releases are recorded only by Git history and your image tags. Export the release history you need for audit before decommissioning the database.

Users, roles and approvals

Octopus users, teams, roles and approval records do not carry over. Rebuild access through your identity provider, mapping groups to Argo CD roles and to Git branch protection for production changes. Decide where approvals now live, in pull request reviews or in sync windows, and document who can sync production manually.

Git webhooks and the CI build

Octopus usually receives a trigger from the CI server when a new package or image is ready. In Argo CD, the CI pipeline builds the image and writes the new tag or chart version into the GitOps repository, and Argo CD picks up the change. Rebuild that pipeline step and its credentials, and confirm webhook settings so Argo CD refreshes promptly.

Notifications and integration endpoints

Octopus sends deployment notifications, Slack or Teams messages and ticket updates through its own integrations. Argo CD provides notifications through its controller, so list each recipient and channel, then confirm which ITSM, change record or audit system expects a deployment event. Test each alert in a non-production environment before cutover.

Migration sequence from inventory to decommission

This sequence moves Kubernetes deployments from Octopus Deploy to Argo CD in controlled stages, so each application is proven in Git and on the cluster before Octopus stops deploying it. It ends with an archived release history and a decommissioned Octopus instance.

Inventory projects, environments and variables
Export every project, environment, lifecycle, target and variable set from Octopus using Config as Code so the process definitions sit in version control. Your platform team and the Octopus administrators do this together, and a named owner signs off each Kubernetes application in scope. Sensitive variables and tenant data stay in the database, so list them separately with their owners and the secrets store where each value will live. The output is a spreadsheet or repository index mapping each application to its cluster, namespace, environment and secrets, with the items that cannot be exported marked for manual handling.
Convert a pilot application to Helm or Kustomize
Pick one low-risk, Kubernetes-hosted application and translate its Octopus steps and variables into Helm charts or Kustomize overlays, with one overlay or values file per environment. Keep the image tag and configuration in Git, and move secret references to External Secrets or a similar operator so no plaintext values enter the repository. Create the Argo CD Application for this pilot in a non-production cluster. The output is a pilot repository and an Application that reports Synced and Healthy for the same workload Octopus deployed.
Set up Argo CD access and RBAC before any sync
Connect Argo CD to your identity provider through its bundled Dex or directly through an existing OIDC provider, and map groups to project roles. Define repositories as Kubernetes Secrets, since Argo CD 3.0 no longer reads them from argocd-cm. Confirm that update and delete permissions apply only to each Application, that log access requires an explicit logs, get permission, and that the built-in admin account is disabled with admin.enabled set to false once SSO works. Review who can sync production Applications and who can change the AppProject source and destination rules. The output is a tested role matrix and a recorded access review.
Run Octopus and Argo CD in parallel on non-production
Keep Octopus deploying the pilot application to non-production environments while Argo CD deploys the same release from Git to a separate namespace or cluster. Compare image versions, configuration values, rollout health and ingress behavior for each release, and record every difference as a defect in the Helm or Kustomize definitions. Confirm that Argo CD's automated sync and self-heal settings do not fight with any remaining Octopus-managed resources. The output is a comparison log with zero unexplained differences for at least one full promotion cycle agreed with the release owner.
Promote through Git and cut over one application at a time
Replace the Octopus lifecycle with a Git promotion path: a change to the staging overlay merges through a pull request, and a production overlay change follows after approval. Once a production Application is synced, disable the Octopus deployment step for that application and keep its last Octopus release available for rollback. Rollback means reverting the Git commit and letting Argo CD sync, so test that path in non-production first. The output for each application is a production Argo CD Application with a documented rollback procedure and an approval record in the Git host.
Retire the Octopus targets and archive the history
After every application has run on Argo CD through at least one production change, remove Octopus targets from the Kubernetes clusters and revoke the service accounts and API keys Octopus used. Export the release history, deployment logs, audit events and variable change records to your long-term archive, and confirm that auditors and incident responders can read it without Octopus. Remove the Octopus Tentacle or Kubernetes agent from clusters and take a final verified backup of the Octopus database before stopping it. The output is a signed-off archive index and a shutdown record.
Decommission Octopus Server and close the access
Stop the Octopus Server and its SQL Server database only after the archive is verified and the retention owner approves the shutdown. Remove the Octopus administrators' access to production clusters, rotate any secrets that Octopus held outside the new secrets store, and update the runbooks and on-call documents to point to Argo CD. Keep the final backup under the retention policy your compliance team sets. The output is a decommission record listing removed credentials, retained archives and the date Octopus stopped deploying.

How the Argo CD side is set up for production

Run Argo CD in its own cluster or, at minimum, its own namespace, separate from the workloads it deploys. The controller holds credentials for every target cluster, so the blast radius of a compromise depends on where it sits. Decide early which clusters Argo CD will manage, and confirm with your platform team how the control plane is reached from each of them. Whatever you choose, repository access must be defined as Kubernetes Secrets, because Argo CD 3.0 removed repository configuration from the argocd-cm ConfigMap. Any runbook or Helm values file that still references the old location will silently fail to connect, so check every migrated manifest before the first sync.

For sign-in, choose between the bundled Dex server, which offers connectors such as SAML, LDAP and GitHub, and direct OIDC with your existing identity provider. Direct OIDC is usually the simpler path when you already run Okta, Microsoft Entra ID, Keycloak or Google Workspace. Map groups to Argo CD roles deliberately, and note that Dex-based RBAC in 3.0 keys on the federated_claims.user_id claim, so test the mapping with a non-administrator account. Once SSO works, set admin.enabled to false so the built-in admin user is disabled. Keep a documented break-glass procedure, and confirm with your security team who may re-enable it and how that event is logged.

For production availability, the high availability manifests need at least three nodes because of pod anti-affinity rules, so a small two-node cluster is not a supported design. Confirm that your cluster is not IPv6-only, since Argo CD does not support that configuration. Argo CD keeps its state in Kubernetes objects, and Redis is a disposable cache, so losing it causes a rebuild rather than data loss; the application controller can be sharded across replicas if the number of managed applications grows. Back up the Kubernetes objects that define your Applications, AppProjects and repository Secrets, because those are the records that must survive a cluster rebuild.

How the migration changes by starting point

A single cluster with a few applications is the simplest starting point. Most of the work is converting each Octopus project into one Argo CD Application that points at a Helm chart or Kustomize overlay in Git. The lifecycle is usually a straight line from a development environment to production, so promotion can be handled by a commit or a pull request into the production path rather than a complex graph of channels.

Process export: Use the Config as Code export to capture each project's steps, then write the equivalent Helm values or Kustomize base by hand, since the export does not produce finished Kubernetes manifests.
Variables: Move plain values into per-environment files in the repository and leave secrets out of Git entirely.
Sync policy: Decide which applications sync automatically and which wait for a manual sync, and set this per application.
Argo CD install: Confirm whether one Argo CD instance is enough or whether you need the high availability manifests, which the upgrade and HA documentation both expect to run on at least three nodes.
Rollback: Test how a rollback works in Git, since Octopus release history will not be available in Argo CD.

Confirm with your team which applications depend on each other and whether any Octopus step runs outside the cluster, such as a database migration, because those steps need their own home in the new pipeline.

What drives the cost and duration of this migration

The effort in moving from Octopus Deploy to Argo CD sits in a few components: how much deployment logic must be converted, how many environments and clusters must be wired up, and how secrets and approvals are rebuilt. Each card below names one component, what it means for the project, and what to confirm in a written scope before a quote is accepted.

Process and variable count

Every Octopus process step and variable set has to become a Helm chart values file, a Kustomize overlay or a plain manifest. The number of projects, steps and variables sets the size of the conversion work more than any other factor. Ask the vendor to count projects, steps and variable scopes from an OCL export before agreeing a scope, and note which steps run scripts that have no direct Kubernetes equivalent.

Tenant complexity

Octopus tenants that deploy the same project with different variables, channels or targets must be mapped to Argo CD Applications, ApplicationSets or per-tenant overlays. Each tenant that shares a pattern lowers the effort, while tenants with bespoke steps raise it. Confirm how many tenants exist, how many differ from the shared template, and who owns each one after cutover.

Environments and clusters

Each environment and target cluster adds a set of Argo CD destinations, sync policies, RBAC rules and network paths from the Argo CD controller. The more clusters, the more sync and access testing is needed in each. Ask the vendor to list every environment, cluster and namespace, and to state whether the Argo CD instance is central or one per cluster, since that choice changes both the build and the upkeep.

Approval and lifecycle design

Octopus lifecycles and manual approvals must be rebuilt as Git promotion steps, pull request reviews, protected branches or sync windows. Approval rules that exist only in the Octopus database are easy to miss. Ask the vendor to map each lifecycle phase and approver group to a Git or Argo CD control, and to document who can override a sync during an incident.

Secrets handling

Sensitive Octopus variables are stored encrypted in the Octopus database and are not exported with the OCL process definition, so their values must be re-entered from a secrets store and wired to the manifests. This is often the slowest item because values must be sourced from their owners. Ask who will supply and verify each value and which secrets store will hold it.

CI pipeline changes and training

Build pipelines that currently call Octopus to create releases must be changed to commit image tags to Git, which Argo CD then syncs. Teams also need training on Argo CD sync, health checks and rollback. Request a written list of CI jobs to change, the number of teams to train, and the training format, and confirm the scope of any ongoing support after the first production release.

Recurring upgrade work

Argo CD ships a minor release four times a year, and only the three most recent minor versions receive patch releases, per the Argo CD release process. Every upgrade of the platform, and of the Helm or Kustomize tooling around it, is recurring effort that should be planned, tested in a non-production cluster and documented. Ask whether the quote covers upgrades for a fixed period or is priced as a retainer.

Questions teams ask before starting the Argo CD migration

How much effort does moving from Octopus Deploy to Argo CD take?

Effort depends mainly on how many projects, environments and tenants the Octopus setup holds, and how much logic lives in custom steps and scripts rather than standard deployment steps. Each Octopus project usually becomes a Helm chart or Kustomize base plus one overlay per environment, and each overlay needs its own Argo CD Application. Variable sets, tenant scopes and lifecycle rules each add translation work. Ask any partner for a written inventory of projects, steps, variables and tenants before agreeing a scope, because that inventory is what the estimate should follow.

What drives the timeline for an Argo CD migration?

The timeline is set by the number of Octopus projects still in active use, the number of clusters and environments, how many approval and lifecycle rules must be reproduced, and whether teams can run old and new deployment paths in parallel. Freeze windows and change-approval cycles in regulated organizations often set the pace more than the engineering work. Plan a parallel period in which Argo CD deploys a low-risk service first, and confirm the schedule against your own change calendar rather than a generic duration.

What does the internal team need to provide during the migration?

The work needs people who know the deployment process, people who own each target cluster and namespace, and someone who can approve changes to Git repositories and production access. Platform engineers need to define the repository layout, RBAC and secrets approach. Application teams need to review the generated manifests and test their services. Confirm named owners for each role before work starts, because gaps there cause more delay than technical problems.

Can our own engineers migrate from Octopus Deploy to Argo CD without outside help?

A team with Kubernetes, Helm or Kustomize and Git experience can migrate a small set of services alone, and Argo CD is open source under the Apache License 2.0 with no paid edition from the project. The harder parts are sensitive variables, which cannot be exported from Octopus and must be re-entered into a secrets store, and the translation of approvals and audit into Git workflows. Decide early which parts your team will own and which need external support, and document that split in the scope.

What happens to approvals and audit trails after moving to Git-based promotion?

Octopus lifecycles and manual approvals are replaced by pull request reviews, protected branches and promotion through Git commits. Audit moves from the Octopus deployment history to Git history plus Argo CD's sync records and Kubernetes events. Argo CD's own user management and RBAC must be configured so that sync and delete rights are restricted, and the built-in admin user should be disabled once SSO or local users are set up, as the user management documentation recommends. Confirm with your auditors which evidence they need and how long Argo CD and Git logs are retained in your environment.

What does Argo CD not cover that Octopus Deploy handles today?

Argo CD is built for Kubernetes. It does not deploy to virtual machines, Windows servers, IIS or Tentacle-style machine targets, and it does not provide Octopus runbooks or a general release dashboard. If your estate includes those targets, keep Octopus or use another tool for them during the transition. Confirm the full target list in your inventory and check the Argo CD documentation for the version you plan to run, since upgrade notes such as the 2.14 to 3.0 changes affect RBAC and repository configuration.

Which Argo CD version should we plan to run?

Argo CD ships a minor release four times a year and supports only the three most recent minor versions with patch releases, so plan for regular upgrades rather than a fixed version. Check the release process and cadence page and the GitHub releases page for the current patch versions before you choose a baseline. Read the upgrade notes for every minor version you cross, because changes such as the 3.0 removal of repository settings from argocd-cm affect how the installation is configured.

How DeployOpen scopes, runs and supports the migration

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For a move from Octopus Deploy to Argo CD, we start with an inventory of projects, lifecycles, variables and targets, then agree the scope in writing before any cluster or repository changes begin.

How we scope

Inventory every Octopus project, environment, lifecycle and target that deploys to Kubernetes today
Agree in writing which applications, clusters and environments move to Argo CD in this engagement
Define how sensitive variables will be stored in your chosen secrets store, and who holds access
Confirm which deployments stay on Octopus during a transition period, such as virtual machines or Windows servers

How we build

Export Octopus processes as Config as Code and convert steps and variables into Helm or Kustomize manifests
Build Git repository layouts with per-environment overlays, promotion paths and sync policies for each application
Configure Argo CD SSO, RBAC and disabled admin account, and define repositories as Kubernetes Secrets
Test each application in a non-production cluster, including rollback and sync failure scenarios, before cutover

How we hand over

Document the repository structure, promotion workflow, approval points and how to add a new application
Provide a runbook for Argo CD upgrades, covering the project's supported minor versions and patch cadence
Walk your platform and release teams through the new process and record the handover sessions
Deliver a mapping of each former Octopus lifecycle and variable to its replacement in Git or the secrets store

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after handover, if you want it
Plan Argo CD upgrades against the project's release cadence and confirm each change in a staging environment
Review access, backup and high availability settings on a schedule agreed in your written scope
Quote follows from the written scope, so ask for line items covering each component and any recurring retainer

Migrate from Octopus Deploy to Argo CD