Argo CD performance with monorepos

Support for the argocd.argoproj.io/manifest-generate-paths annotation without webhooks arrived in v2.11, so any older release needs a different approach. Confirm the exact version you run in production, not the one in your test cluster, and check it against the Argo CD high availability guide. Your platform team owns this check because it depends on the installed image tag. Ask them to record the version in the change ticket, then confirm during a test sync that a commit outside the declared path leaves the Application's status untouched. If the version is older than v2.11, plan an upgrade first, because the upgrade path itself has breaking changes to review.

Path-scoped refresh depends on how and whether your Git host delivers push events, so inventory each provider before you change any annotation. Confirm with your source control administrators which hosts send webhooks, which events they include, whether payloads reach Argo CD's endpoint from the network where it runs, and who holds the shared secret. Also check whether a proxy or web application firewall truncates large push payloads, since a monorepo push can carry many changed files. Without a delivery path, Argo CD falls back to periodic polling, so the annotation still limits regeneration but refresh timing is less predictable. Write down the answer for each repository.

Shallow clones disable the Git-history comparison that path-based refresh relies on, so a shallow repository may regenerate more often than you expect. Ask your repository owners whether any Application uses a shallow clone configuration, and whether the repo-server or a plugin enables one. Then test one application with a commit that touches only its own path and one that touches a neighboring path, and compare what Argo CD regenerates. Anyone who changes clone depth for speed should understand that the trade-off lands on refresh behavior, so review it with the team that owns the repository and the Argo CD administrators together.

Path boundaries work only when each application's inputs sit in directories that other applications do not read. Check whether shared Helm charts, common Kustomize bases, or values files outside an application's folder feed several Applications. If they do, a commit to the shared directory correctly triggers regeneration for every consumer, but the annotation cannot narrow it further. Ask the platform architects to map each Application's source path and every external reference it resolves, then decide whether shared content should move into its own declared path or stay where it is. This mapping usually takes longer than the annotation change itself, so budget review time with the application owners.

Three groups should sign off: Argo CD administrators, source control administrators and the application teams that own each path. Argo CD administrators confirm the version, controller and repo-server configuration, and whether webhooks reach the endpoint. Source control administrators confirm delivery of push events, payload limits and secret handling. Application teams confirm which directories their Applications really read, including shared charts and values. Record each answer in the runbook for the repository. If one group cannot answer, treat that repository as not ready for path-scoped refresh and keep its current behavior until the answer arrives.

The annotation itself is a small configuration change, so most of the cost comes from discovery, testing and review. Internal teams pay for their time to map paths, run test commits and update runbooks, and an upgrade to a supported version adds its own effort. A partner, if you hire one, bills for the scoped work in a fixed-scope quote, which is agreed in writing before work starts. Ask for the quote to list the repositories in scope, the version checks, the webhook verification steps and the test plan. Costs recur only when repositories are added or layouts change, so ask whether a retainer would cover that ongoing review. DeployOpen does not publish a price list, so the written scope determines the figure.

Verify with controlled commits, then check what Argo CD actually regenerated, rather than assuming the annotation works. Create a test branch, change one file inside an Application's path and another file outside it, and watch the Application's refresh and manifest generation events. Repeat the test once with webhooks enabled and once with polling only, because the delivery path changes timing. Keep the test results with the change record so auditors and operators can see the evidence. If the outside commit still triggers regeneration, check the shallow clone setting, the annotation spelling and the version first.

The cost follows the amount of analysis and change needed, mostly the number of Applications and ApplicationSets that point into the repository, how many distinct paths and tools (Helm, Kustomize, plain YAML) they use, and how many clusters and environments must be tested. Each Application needs its generate paths reviewed, so a repository with hundreds of Applications carries more work than one with a few dozen. Git host configuration adds effort when webhooks must be created, secured and verified per provider. Testing is often the largest variable, because a wrong path filter can silently skip a needed sync. Ask any provider for a written scope that lists these counts, the Git hosts involved, and what evidence of testing you will receive. DeployOpen fixes scope and deliverables in writing before work starts, and the quote follows from that scope.

Duration depends on the same drivers as cost: the number of Applications, the complexity of their path layouts, the Git hosts and webhook work involved, and the testing required before a change reaches production. A narrow scope covering one repository and a handful of Applications is far shorter than a rewrite of how an entire organization models its monorepo. Because most engagements are fixed-scope, the timeline is agreed in writing alongside the deliverables rather than estimated in the abstract. Ask for milestones that separate analysis, a staging rollout and production cutover, since a staging rollout is where slow or missed refreshes are caught. Your scoping conversation should also confirm change freeze windows, because those set the earliest practical production date.

The work needs decisions and access from your side more than it needs time from every developer. You will need an owner who knows the repository layout and which directories each team's applications read, read access to the Argo CD configuration and Application manifests, and administrative access to the Git host so webhook endpoints and shared secrets can be configured. Someone must also confirm which branches and tags each Application tracks, because the fully qualified target revision change depends on it. Finally, your platform team needs to approve the change window and the rollback approach. Put these responsibilities into the written scope so that a missing approval does not become a hidden delay.

Yes, many teams can, provided they have engineers who understand Argo CD's reconciliation model and can test changes safely. The core techniques are documented in the Argo CD high availability guide, including the manifest-generate-paths annotation, fully qualified refs such as refs/heads/main in targetRevision, and the ARGOCD_RECONCILIATION_JITTER setting. The risks sit in the details: a path filter that is too narrow can stop a required sync, shallow clones remove the Git-history comparison that the annotation relies on, and webhook misconfiguration can leave applications refreshing late. If your team has the capacity to write tests for each Application's paths and to monitor refresh behavior after the change, doing it internally is practical. If not, a fixed-scope engagement can cover the analysis and testing while your team keeps ownership of the result.

The most common failures come from path filters that exclude files an Application actually renders. An Helm chart that reads a values file from a shared directory, or a Kustomize overlay that references a base outside its folder, can stop updating if the annotation does not list those paths. Shallow clones are another trap, because they disable the Git-history comparison the annotation uses, so teams should confirm how their repo-server fetches repositories before relying on it. Webhook gaps are also common, particularly when branch or tag naming does not match what the Application tracks. Before cutover, verify that a commit touching each shared path triggers the expected refresh, and keep a documented way to force a hard refresh if something is missed.

They can, mainly because the repo-server runs Helm and Kustomize on repository content, so the paths an Application reads are part of your trust boundary. Path filters should narrow when regeneration happens, not widen what the repo-server can read. Webhook endpoints should use shared secrets, and the Argo CD security documentation covers TLS between components and redaction of credentials in logs and API responses. Changes to repository credentials should follow the same review process as other access changes. Ask the scope to include a review of who can change Application path annotations, since a single edit to an annotation can alter what gets deployed.

A useful scope lists the Argo CD version and installation you are running, the number of Applications and ApplicationSets in scope, each repository and its Git host, and the tools each Application uses. It should name the changes to be made, such as annotations, target revision format and webhook configuration, and the test evidence you will receive for each one. Ask who performs staging and production cutover, what rollback looks like, and what the client team must provide and approve. Confirm whether follow-up support or a retainer is included after go-live, because refresh behavior often needs review once real commit traffic arrives. Finally, check that the scope states what is excluded, so the quote reflects the work you actually need.