When teams adopt GitOps, one of the first design decisions they face is how to separate environments. Splitting dev/staging/production by Git branch feels natural — it's just an extension of Git Flow. But in a Kubernetes GitOps context, this design is a textbook anti-pattern, and left unaddressed, it can corrupt the actual state of your production clusters.
1. The "safe separation" you thought you had is quietly falling apart
Branch-based separation makes sense for versioning application code. Cutting a feature branch, going through review, and merging into main is a workflow most development teams already know well. That familiarity is exactly why many teams apply the same logic to Kubernetes manifests and infrastructure config, splitting them into a "dev branch," a "staging branch," and a "production branch."
In a GitOps context, though, this becomes an anti-pattern outright. Octopus Deploy's blog explicitly frames modeling environments with Git branches as "a relic of the past," pointing out that Helm and Kustomize were designed from the ground up around plain file structures for multiple environments — not branches. Branch-based operation runs directly against that design philosophy.
Platform Engineering.org is just as direct, calling branch-per-environment "an anti-pattern for most teams" and naming three concrete consequences: merge conflicts, the difficulty of comparing state across environments, and a violation of trunk-based development principles. This design debt only gets more expensive to unwind as your cluster count grows. It's worth keeping in mind, even at this early stage, that managed Kubernetes with GitOps built in natively is an option on the table.
2. It's not just merge conflicts — the real problem is Git's "intent" drifting from the cluster's "reality"
The surface-level symptom of branch separation is merge conflicts and configuration drift between environments. An emergency patch goes straight into the production branch, never gets backported to staging, and before anyone notices, the environments have quietly diverged. Any GitOps operator has lived through some version of this incident.
But the deeper problem runs further down. At the core of GitOps is the principle that Git is the single source of truth. The CNCF's OpenGitOps project defines four principles — Declarative, Versioned and Immutable, Pulled Automatically, and Continuously Reconciled — all of which assume that what's declared in Git and what's actually running in the cluster stay in lockstep.
Meanwhile, the actual state of a Kubernetes cluster, as the official Kubernetes documentation explains, lives in etcd, the control plane component responsible for maintaining a consistent view of cluster state. In a setup where branches keep splitting and merging, it becomes practically impossible for a human to accurately track which branch's content is reflected in which cluster's etcd at any given moment. The gap between Git's diff and production reality isn't an operational mistake — it's a structural limit of the design itself.
3. The migration pattern: directory structure plus trunk-based operations
The way out is straightforward. Represent environment separation with directories (folders) instead of branches, so every environment tracks the same main branch while referencing different artifact versions.
Google Cloud's official GitOps best practices guide explicitly recommends a folder-based approach, noting that folders make changes easier to detect and syncing across multiple clusters simpler than branches do. The same guide also proposes splitting repositories by role — packages, platform, application configuration, and application code — reflecting a design philosophy where repository structure mirrors team ownership.
With this structure in place, a promotion is no longer "merging a branch" — it's "a commit that rewrites the image tag inside a manifest." As the official Argo CD documentation defines it, GitOps treats a Git repository as the source of desired state and automatically, declaratively reconciles changes against it. A directory-based structure lets that mechanism work exactly as intended. For larger organizations, Akuity's GitOps best practices whitepaper points out that the choice between a single repo and multiple repos is really shaped by organizational structure — and more teams are pairing this with dedicated tooling that treats cross-environment promotion as a first-class concept. Kubo Cloud ships with ArgoCD/Flux integration built in, so you don't have to build this directory-based migration from scratch — including Helm chart support — and can start putting it into practice right away.
4. What breaks when your fleet grows from 10 clusters to 100
Even after migrating to a directory-based structure, a new wall appears once your fleet scales up. According to a deep-dive from OneUptime, once a single Argo CD instance manages more than 100 clusters, the application controller's memory footprint balloons because it keeps every resource from every cluster cached in memory, and the repo server starts to lag on manifest generation too. The larger the matrix of clusters times applications gets, the more that load grows — exponentially.
The standard way past this wall is a federated architecture: deploy regional Argo CD instances that each manage 20-30 clusters, and tie them together with a meta-instance that oversees the whole fleet. To generate Applications for individual clusters, the ArgoCD ApplicationSet Cluster Generator — using label selectors to target the right clusters — has become the standard practical pattern as of 2026. If you haven't already solved your branch design problem, this is the stage where even thinking about a scaling strategy becomes exponentially harder.
Conclusion: pay off your branch-design debt before your cluster count grows
Branch-based environment separation in GitOps is a form of debt that's easy to miss early on. Beneath the surface-level annoyance of merge conflicts lies a structural problem: Git's declared intent and the cluster's actual state drifting apart. Migrating to a directory structure and trunk-based operations costs far less when you do it while your cluster count is still small — and it keeps your options open as your fleet grows from 10 clusters to 100.
Building this kind of GitOps setup from scratch takes real time and effort. Kubo, a managed Kubernetes service built on K3s, ships with ArgoCD/Flux integration out of the box, so you can start from a directory-based GitOps configuration that's already in place. Multi-cluster management and visibility run on a Rancher-based control plane, giving you the operational foundation you'll need as your multi-cluster footprint grows from 10 clusters to 100.
Do you build a GitOps platform from scratch on EKS or AKS and keep re-architecting it yourself every time you need to scale — or do you focus on fixing your branch design on top of a platform that already has this integrated? If you want to take stock of your own setup against what's covered here, start by checking Kubo's pricing plans for a cost comparison against EKS/AKS, or get in touch to talk through your current GitOps setup.