Patterns and conventions

Recurring patterns in the Argo CD codebase. Following them keeps PRs reviewer-friendly.

Backend (Go)

Module and packages

• Module path is github.com/argoproj/argo-cd/v3. Always use the /v3 import prefix.
• Internal helpers live under util/<area>/. Public APIs live under pkg/.
• Each binary's command package sits in cmd/<binary>/commands/. The single cmd/main.go dispatches based on os.Args[0] (see cmd/main.go).

Cobra commands

CLI and server entry points use spf13/cobra. Conventions:

• A package exports NewCommand() returning a fully-wired *cobra.Command.
• Persistent flags go in cmd/argocd/commands/root.go for the CLI; per-binary flags go in their own commands/argocd_*.go files.
• Use cli.SetLogFormat / cli.SetLogLevel (util/cli/) in cobra.OnInitialize.

Logging

• Use logrus via util/log/.
• Component-level loggers add fields like application, revision, namespace.
• klog (Kubernetes) is redirected to logrus in cmd/main.go init().

Errors

• Wrap with fmt.Errorf("...: %w", err); never lose the cause.
• Top-level error helpers live in util/errors/. Use errors.CheckError only at process boundaries.
• gRPC errors should be status.Errorf(codes.X, ...) so the API server returns proper HTTP status codes.

gRPC + REST

• Service definitions live in *.proto files alongside the implementation (server/application/application.proto, server/repository/repository.proto, etc.).
• Generated stubs live in pkg/apiclient/<service>/. Regenerate with make codegen.
• The API server uses gRPC-Gateway to expose REST endpoints from the same proto definitions.

CRDs and types

• All CRD types live under pkg/apis/application/v1alpha1/.
• Run make codegen after editing types — it regenerates generated.pb.go, openapi_generated.go, deepcopy, and CRDs under manifests/crds/.
• Run make manifests to regenerate the install YAML bundles.

Configuration

• Cluster-wide config is in the argocd-cm ConfigMap and argocd-secret Secret, read via util/settings/settings.go.
• Per-component flags read environment variables through util/env/ (env.ParseNumFromEnv, env.StringFromEnv).
• Common envs and defaults live in common/.

Caching

• Two-level cache (in-memory + Redis) is in util/cache/cache.go.
• The application-state cache (util/cache/appstate/) and repo-server cache (reposerver/cache/) wrap it for component-specific keys.

Concurrency

• Application controller uses workqueues with rate limiters (pkg/ratelimiter/).
• ApplicationSet controller uses controller-runtime reconcilers.
• Goroutine leaks are guarded with go.uber.org/goleak in tests; respect the existing context propagation pattern.

Frontend (TypeScript / React)

• Single-page React app under ui/src/app/.
• Built with webpack (ui/src/app/webpack.config.js), tested with Jest (ui/jest.config.js), linted with ESLint (ui/eslint.config.mjs) and Prettier (ui/.prettierrc).
• The compiled bundle is embedded into argocd-server via ui/embed.go.
• API clients for the gRPC-Gateway REST endpoints live in ui/src/app/shared/services/ (typical ApplicationService, RepositoryService, etc., paralleling the Go side).

Manifests and Helm/Kustomize

• The Kustomize bases under manifests/base/ are the source of truth.
• manifests/install.yaml, core-install.yaml, namespace-install.yaml, and the -with-hydrator variants are generated artifacts — never edit them by hand. Use make manifests.
• Resource customizations (per-CRD health/actions) live under resource_customizations/<group>/<kind>/.

Documentation

• docs/ is a MkDocs site (mkdocs.yml).
• New user-facing functionality requires a docs change in the same PR, per AGENTS.md.
• Use GitHub-style admonitions (> [!NOTE], > [!WARNING]); the script hack/admonitions-to-alerts.sh converts between styles when needed.

Generated vs. hand-written

If a file starts with // Code generated by ... DO NOT EDIT. (or has zz_generated / generated.pb.go in the name), edit the source and regenerate, never the file itself. Common generators:

Tool	Output
protoc (hack/generate-proto.sh)	*.pb.go, gRPC stubs, OpenAPI
mockery (.mockery.yaml)	mocks/ packages
controller-gen (hack/update-codegen.sh)	deepcopy, CRDs
openapi-gen (hack/update-openapi.sh)	openapi_generated.go
kustomize build (hack/update-manifests.sh)	manifests/install.yaml and friends