Argo CD is the leading GitOps solution for Kubernetes. It excels at syncing manifests to clusters and gives engineers a powerful UI to verify and troubleshoot deployments.
However Argo CD was never designed to handle the full software delivery cycle. While platform teams can use it for cluster bootstrapping and configuration management, most real-world delivery pipelines require multiple environments, tests, security and compliance checks, change management, and many other steps. Today, many teams work around this gap by stitching together tools like Jenkins or GitHub Actions and Argo CD with custom scripting. This quickly becomes brittle. As the number of Argo CD instances, Applications, and clusters grows, so does the maintenance overhead. Engineers also lose centralized visibility and must jump between different Argo CD dashboards to understand deployment status.
Octopus solves deployment challenges at scale. As a complete CD platform, it provides guardrails, orchestration, and visibility. We realised that combining Argo CD and Octopus would allow our users to get a solution that can scale and has both great CD and GitOps capabilities. Now, with built-in support for Argo CD, teams can eliminate custom glue code and combine the strengths of both approaches out of the box.
This post introduces Argo CD in Octopus and shows how to get started.
Argo CD in Octopus is currently in Early Access, rolling out to Octopus Cloud in early October.
What is Argo CD?
Argo CD is a declarative, GitOps-based tool for deploying Kubernetes manifests. Following the GitOps principles, it continuously monitors Git repositories for changes and ensures that the cluster state matches the desired state described in those repositories.
Why is it good?
Argo CD makes Kubernetes delivery predictable and transparent. Configuration is stored as code in Git, so every deployment is versioned, auditable, and easy to roll back. Engineers can rely on Git history to know exactly what is running in a cluster. Developers don’t need direct cluster access—they simply commit changes using familiar tools and workflows, and Argo CD applies them.
A major advantage of Argo CD over many other GitOps tools is its built-in UI. The dashboard gives teams real-time visibility into application health and sync status, reducing the need for extra tooling to verify or troubleshoot deployments.
Argo CD’s limitations
It’s important to be clear about what Argo CD was designed to do and what it was not. Argo CD excels at synchronizing manifests to Kubernetes, but it is not an end-to-end Continuous Delivery solution. In practice, teams often combine it with CI/CD tools to orchestrate broader delivery pipelines. Many of Argo CD’s limitations show up when it is stretched beyond its intended scope.
Environment promotions
Successful software delivery involves more than updating a single cluster. Changes typically progress through a series of environments, with tests and approvals at each stage. Some teams try to model this workflow directly in Git, automating Git updates with scripts, but Git was not built for environment promotion management. As a result, promotion logic can become brittle and hard to maintain, especially at scale.
Octopus solves this with advanced Environment Lifecycle modelling, providing enforced guardrails that reduce the risk of premature production changes.
Complex orchestrations
Argo CD’s job is to sync Kubernetes manifests. Real-world deployments often require much more — database migrations, external cloud resource updates, integration tests, compliance checks, notifications, and monitoring. Teams can add scripts or tools to cover these steps, but doing so outside of Argo CD creates fragmentation. This disjointed approach is error-prone and makes it difficult to reason about the state of the system as a whole.
Enterprises also deploy more than just Kubernetes workloads. VMs, serverless functions, and SaaS integrations are common, but Argo CD alone cannot unify these deployment targets.
Octopus solves this through its broad library of Steps and Deployment Targets, covering Kubernetes, Argo CD, and much more.
Rich RBAC controls
While ArgoCD integrates with Kubernetes RBAC, it lacks fine-grained role-based access control for approvals, gates, and deployment responsibilities across environments. For organizations in regulated industries, this can make it difficult to enforce compliance requirements or maintain clear audit trails.
The audit trail that can be found in git history might provide some record after the fact, but git was never built with fine-grained permissions in mind, particularly when coupled with the complex access configurations required for multi-team environment promotions or more advanced compliance and governance requirements.
Octopus solves this through the customizable RBAC controls, external ITSM integrations and (coming soon) Policies.
Multi-cluster management
Argo CD supports several different installation topologies for managing multiple clusters, each with their pros and their cons.
The “hub and spoke” model allows for a single Argo CD instance to manage multiple clusters, however it requires opening up access to each cluster and does not provide very good isolation or security. A popular alternative model, is installing a “standalone” ArgoCD instance in each required cluster. This reduces some scaling and isolation concerns however there is now additional management and access complexity that is introduced in its place.
Octopus solves this by providing a single pane of glass through which you can view your application’s sync state, regardless of the underlying cluster that they are running on. While Octopus doesn’t currently manage the Argo CD instances themselves, the projects that your team cares about can all be presented in one place. The job of keeping the state in sync remains left to Argo CD, but this state is directed by Octopus through your git manifests.
Introducing Argo CD with Octopus
Octopus has had native support for Kubernetes for many years, most recently with our own live object status capability. We know that some customers want to leverage the strengths that Argo CD provides in supporting GitOps workflows. We can now provide capabilities in Octopus to get the best of both products, leveraging the strong points of each without sacrificing what makes both Argo CD and Octopus useful and without trying to hide the fact that Argo CD is playing its role.
Let’s take a look at how this new feature works. This blog post won’t explore all the possible configurations but instead run through some of the highlights as well as discuss some of our suggested best practices to make the most of these new capabilities.
Declarative integration
In providing Argo CD integration into Octopus Deploy, it was important to us that we provide a model that would align with the way that typical users of Argo CD want to work. This means that rather than thinking of Argo CD as a typical Octopus target, we instead automatically use declarative annotations stored in the Application manifests from connected instances.
Since each Application in an Argo CD instance typically maps to a specific deployable app in a specific environment (perhaps per cluster), a series of annotations can be added to the declarative Application manifest to signal to Octopus which are relevant for a given Project and Environment deployment context.
No need to configure each application in Octopus, just connect your Argo CD to Octopus and your declarative configuration does the rest. This configuration more naturally fits into the GitOps mindset that is prevalent in Kubernetes pipelines.
Deployments are commits
In Octopus, a deployment is the execution of a pipeline in the context of an environment. A successful deployment means every step in the pipeline has been completed. For Kubernetes, this might involve applying manifests with kubectl or upgrading Helm charts with helm upgrade.
Argo CD, however, works differently. Its core responsibility is to synchronize the contents of a Git repository with a Kubernetes cluster. This means that during a deployment, Octopus modifies the desired state in Git, and Argo CD takes care of reconciling those changes to the cluster.
We’ve modelled Git updates as deployment steps in Octopus. This lets you combine GitOps-driven updates with the rest of your delivery process. For example, you can run a database migration before promoting an Application through Argo CD, execute smoke tests after the update, and send a Slack notification if those tests fail.
Argo CD connectivity
The first thing you will need to do is to set up the connection between Octopus Deploy and your Argo CD instances.
Connecting your Argo CD instance involves running an Octopus-Argo CD Gateway in the cluster alongside each Argo CD instance, and we provide a similar helpful Helm installation flow to that used our popular Kubernetes Agent.
As part of this process, there is also the option to scope the connection to specific environments or, when relevant, tenants. Used in conjunction with Octopus Deploy’s RBAC system, this configuration provides one example where stricter controls can be optionally placed around your Argo CD instance and, by extension, deployments to the applications it manages.
New Octopus steps
This first release of Argo CD integration introduces two new steps that make promotions of Argo CD Applications easier and safer.
Update Argo CD Application Image Tags
Most changes to Kubernetes manifests are simple container image tag updates. For every infrastructure change, there are usually dozens—or even hundreds—of new application versions to deploy.
If your team manages manifest files through a separate promotion process (manual or automated) but needs a reliable way to detect new builds, update container tags, and safely promote them through environments, the Update Argo CD Application Image Tags step handles this.
When an Octopus deployment runs, it looks for Argo CD Applications annotated for the relevant project and environment. For each discovered Application (across one or many Argo CD instances), Octopus retrieves the Git location, updates the image tags in the manifests (or Helm values files), and commits the changes.
Argo CD then detects the change and syncs the updated manifests to the cluster.
Update Argo CD Application Manifests
The second step supports more complex scenarios and introduces a stricter approach to managing manifests.
Unlike the Update Argo CD Application Image Tags step, which modifies existing files in an Application’s source folder, this step copies one or more files from a designated input folder and commits them into the Application source.
During a deployment, Octopus commits the selected files. Any files with the same name are overwritten.
Argo CD then syncs those changes to the cluster.
What does this enable?
- Full manifest control – You can modify, add, or remove any fields in your manifests, not just image tags.
- Application creation – You can create manifests for entirely new Argo CD Applications. For example, when creating a new tenant, environment, or cluster, Argo CD (with ApplicationSets if configured) will create a new Application, and Octopus will pick it up and generate the manifests with the next deployment.
- Stricter governance – By overwriting files, this step enforces a single source of truth. Even if someone makes direct changes in an Application’s
sourcefolder, Octopus can reset them during the next deployment. This ensures only tested, approved configurations flow into production.
What can go in the input folder?
- Shared files – The simplest option is a single file (such as Helm values) applied across environments. Updating the file before deployment creates a clear, auditable history of changes in Git.
- Environment-specific configurations – For per-environment differences, you can either maintain separate folders or treat files as templates. Octopus variables can replace placeholders during deployment, injecting the correct values for each environment.
This flexibility lets teams choose between lightweight image updates and strict manifest ownership, depending on their governance and security needs.
Best practices
We designed this feature with established Argo CD best practices in mind. Following them helps you get the most value from Octopus and avoid common pitfalls. This isn’t a full guide to GitOps and Argo CD best practices, but here are a few that are especially relevant when using Octopus with Argo CD:
- Avoid putting environment configuration directly in Argo CD Application manifests. Applications should describe how to deploy, not encode environment-specific details.
- Keep values files separate from the application source. Store them in dedicated locations so they can be promoted and managed consistently across environments.
- Separate manifest repositories from application code repositories. This makes pipelines cleaner and avoids coupling application development with infrastructure changes.
- Be cautious with Helm for internal applications. Helm can be useful, but for simple services, you may not need the overhead. Additionally, if Applications from different environments reference the same Helm chart, updating the chart will result in simultaneous changes to all Applications. A more secure approach would be to promote these changes through the environments instead. If you use Helm, keep a copy of the chart per environment to prevent cross-environment drift.
For more context, see Argo CD anti-patterns from one of our Argo CD maintainers, and this guide on structuring repositories with ApplicationSets.
Current limitations & future plans
Our goal with this first offering is to provide the core capabilities required to perform a deployment to a Kubernetes cluster via Argo CD. As such, we plan to continue investing in further features as well as improve the capabilities initially delivered.
Talking to Argo CD users, we found that about 50% polled liked having the ability to make direct changes to the manifests that Argo CD is watching to quickly push changes that might bypass typical promotion mechanisms. The other 50% preferred managing centralized templating repositories using tools like Helm or Kustomize and enforcing that all changes must be promoted through successive environments. Confusingly, a not-insignificant percentage wanted the capabilities of both patterns at once!
To move fast, we have built on top of Octopus’s current systems, and this means that particularly large repositories may take time to clone. Since the industry best practices are to separate your application code repository from your infrastructure manifests, we expect that this shouldn’t be a problem for most users; however, we are investigating some promising improvements that can be made.
How to try it out
Argo CD in Octopus is currently in Early Access, rolling out to Octopus Cloud in early October.
If you’re an Octopus Cloud user, there’s nothing extra required to enable the feature. Simply open the Argo CD Instances section under Infrastructure, and connect one of your Argo CD instances to Octopus. From there, you can start modeling deployments that combine GitOps and Continuous Delivery out of the box.
Conclusion
Argo CD is a powerful GitOps tool for Kubernetes, but it wasn’t built to manage the full software delivery lifecycle. Octopus complements Argo CD by adding environment promotions, orchestration across diverse workloads, fine-grained RBAC, and centralized visibility across clusters.
With Argo CD integration, Octopus lets teams combine the strengths of GitOps and Continuous Delivery without building custom automation. You get the reliability of Git-driven deployments and the safety, governance, and flexibility of a full CD platform—all in one place.
Happy deployments!
