Optimizing GitOps at Scale with Shallow Clones in Argo CD
Alexander Matyushentsev
Availability: Shallow Clone support will be included in Argo CD v3.3.
Today, we’re sharing shallow clone support, a new feature designed and contributed by the Akuity team as part of our continued investment in making Argo CD scale reliably for large GitOps environments.
TLDR: INT
Large mono repos are often used to simplify code management, but they can slow down GitOps because the repo-server must clone the entire Git history just to check out a single commit. The Akuity team contributed a new shallow clone feature to Argo CD that fetches only the commit Argo CD needs. This cuts clone time from minutes to seconds and removes a major performance bottleneck for teams running Argo CD at scale.
Argo CD for GitOps
Launched more than a decade ago, Argo CD is one of the most widely adopted GitOps operators in the Kubernetes ecosystem. We originally built Argo CD to streamline Kubernetes adoption at Intuit. Today, major organizations use Argo CD to keep clusters synchronized with the desired configuration stored in Git and to provide a proven workflow, intuitive UI, multi-tenancy support, and cross-cluster management capabilities.
In most environments, engineers update manifests, commit changes, and let Argo CD automatically reconcile those updates to clusters. As usage scales, Git operations handled by repo-server become increasingly important to performance.
GitOps as a Service
Rather than running a separate GitOps instance for every team, many organizations centralize on one or two shared Argo CD instances. This “GitOps as a Service” model reduces operational overhead and gives application teams a consistent, self-service deployment workflow.
In this setup, a single Argo CD instance and its repo-server often serve many teams and applications at once. When those applications are sourced from large mono repositories, repo-server becomes a critical scalability point. Even small inefficiencies in how repositories are fetched or processed can impact many applications simultaneously.
The Challenge of Mono Repositories
Mono repositories are common in large organizations, often used to simplify management by storing configuration for many applications, sometimes hundreds, in a single Git repository. While this approach reduces repository sprawl, it also introduces performance and scalability challenges.
The repo-server clones each repository once and reuses that working copy for manifest generation. However, different applications can reference different commits or branches, which requires a repo-server to isolate operations to avoid race conditions.
This limitation historically allowed only one manifest generation per repository to run at a time. When a mono repository received a new commit, it could trigger hundreds of manifest generation requests competing for the same repository lock, significantly slowing processing.
These repositories also tend to grow to several gigabytes in size. Fully cloning them can take minutes and consumes considerable storage and bandwidth.
Reducing Repo-Server Load Through Incremental Optimizations
As the original creators of Argo CD, the Akuity team continues to invest heavily in improving its scalability and performance. Before introducing shallow clone support, we focused on reducing load and contention in repo-server through a series of targeted optimizations.
1. Concurrent Processing by Commit
Repo-server now groups concurrent requests by commit SHA and processes all applications referencing the same commit in parallel. This allows Argo CD to efficiently handle bursts of manifest generation requests triggered by a mono repo update, dramatically improving responsiveness and throughput.
2. Cross-Commit Manifest Caching
Manifest results are cached by commit SHA. When a new commit arrives, Argo CD verifies whether the change affects a specific application’s path. If not, previously generated manifests are reused, avoiding unnecessary regeneration.
Together, these improvements significantly reduced load and improved responsiveness in large-scale deployments. However, even with better concurrency and caching, we consistently observed another bottleneck that could not be addressed in the same way: the cost of cloning very large repositories.
Going Further with Shallow Clone Support for Massive Repositories
Despite earlier optimizations, one major cost remained unavoidable: repository size.
Mono repos with long histories and frequent updates can take minutes to clone. Some teams attempted workarounds such as pre-cloning repos using init containers, but these approaches added complexity and were difficult to maintain.
To address this, the Akuity team designed and contributed shallow clone support to Argo CD, targeting one of the most expensive remaining Git operations in large installations.
With shallow clones, repo-server fetches only the required commit instead of the entire Git history. This reduces clone time, disk usage, and Git bandwidth consumption. The improvement is immediate and significant:
faster initial syncs
lower storage footprint for repo working copies
reduced load during repo-server restarts
more predictable scaling for environments with many applications referencing the same large repository
How to Enable It
Shallow clone is configured per repository. Add shallowClone: "true"to the Kubernetes Secret representing the repository:
apiVersion: v1
stringData:
shallowClone: "true"
type: "git"
url: "https://github.com/argoproj/argocd-example-apps.git"
kind: Secret
metadata:
annotations:
managed-by: argocd.argoproj.io
labels:
argocd.argoproj.io/secret-type: repository
name: my-repo
namespace: argocd
type: Opaque
Benchmarks
In internal benchmarks, shallow cloning reduced initial repository preparation time from several minutes to just seconds - a substantial improvement for large mono repos. For example, the initial clone of https://github.com/opendatahub-io/notebooks.git was reduced from 57 seconds to 1 second:
Full clone:
{
"args": "[git fetch origin --force --prune --tags]",
"dir": "/var/folders/tz/0snjf0fn797fg_98ttt929tw0000gn/T/_argocd-repo/88e5575a-2bbd-4bb6-8697-c7a31791d810",
"level": "info",
"msg": "Trace",
"operation_name": "exec git",
"time": "2025-10-20T16:58:53-07:00",
"time_ms": 57202.157290999996
}
Shallow clone:
{
"args": "[git fetch origin 8adf444fa4f489cd5b34d7fce14f94795812393b --depth 1 --force --prune]",
"dir": "/var/folders/tz/0snjf0fn797fg_98ttt929tw0000gn/T/_argocd-repo/8a80dbdc-cddd-439b-a11d-b26e1a10789e",
"level": "info",
"msg": "Trace",
"operation_name": "exec git",
"time": "2025-10-20T17:11:00-07:00",
"time_ms": 988.406917
}
This optimization removes one of the most costly steps in working with large repositories in Argo CD.
Conclusion
As organizations adopt GitOps across more teams, environments, and applications, the challenge shifts from defining workflows to operating GitOps reliably at scale. Repository size, Git performance, and reconciliation efficiency become critical to keeping GitOps fast and predictable. We are excited to see the Argo CD project continue to grow and innovate withoptimizations such as commit-based concurrency, cross-commit caching, and now shallow clone support that enable teams to run GitOps at scale.
Interested to learn more about other recent Akuity contributions to Argo CD? Check out:
Argo CD MCP Server
OCI-based repository support
Looking for more?
Explore the docs.
For questions, discussions, and to connect with other users and the maintainers, join the Akuity Community Discord server.
If you're interested in other helpful tools created by the minds behind the Argo Project, try out the Akuity Platform today for a supercharged Argo CD experience. Request a demo here for more details.
