Getting started

This page is for engineers who want to build, run, and test Argo CD from a checkout of the argoproj/argo-cd repository. For end-user installation see https://argo-cd.readthedocs.io/en/stable/getting_started/.

Prerequisites

Argo CD is built and tested on Linux/macOS. The required toolchain is documented in hack/tool-versions.sh and the canonical Makefile.

Tool	Why
Go (>= the version pinned in go.mod, currently 1.26.1)	Backend builds, tests, codegen.
Node.js + pnpm (ui/.nvmrc, ui/package.json)	Web UI builds and tests.
Docker (or Podman)	Running test/dev containers, building images, running the e2e fixture.
kubectl and a local cluster (k3d, kind, minikube, or Docker Desktop)	Required for e2e tests and integration runs.
kustomize, helm	Manifest generation and dev installs.
goreman	Used by the dev Procfile to run all components locally.
protoc and friends	Only needed if you regenerate proto/openapi via make codegen.

The repo provides a containerized toolchain (Dockerfile.dev, hack/Dockerfile.dev-tools) so you can run all the make targets inside a fully-pinned image instead of installing tools locally.

Cloning and dependency setup

git clone https://github.com/argoproj/argo-cd.git
cd argo-cd
go mod download
(cd ui && pnpm install --frozen-lockfile)

Building

The Makefile is the single source of truth.

Target	Effect
make build	Builds the unified argocd binary into dist/.
make cli	Builds just the CLI (argocd).
make image	Builds the all-in-one container image.
make manifests	Regenerates the install YAMLs under manifests/.
make codegen	Regenerates protos, OpenAPI, deepcopy, mocks, CRDs. Required after editing API structs.
make build-ui	Webpack build of the UI bundle.
make lint	Runs golangci-lint (config: .golangci.yaml).
make lint-ui	Runs ESLint and Prettier checks for ui/.
make test	Runs Go unit tests across all packages.
make test-e2e	Runs end-to-end tests under test/e2e/.
make help	Lists every documented target.

Running locally

The fastest way to get a full local stack is the dev Procfile:

goreman start

Procfile in the repo root launches every component (controller, API server, repo server, ApplicationSet controller, notifications controller, commit server, CMP server, dex, redis, UI dev server, and a fixture git server). All processes run with ARGOCD_FAKE_IN_CLUSTER=true, hit a local kubeconfig, and use /tmp/argocd-local/... for mounted secret data.

The Tilt-based workflow (Tiltfile, Dockerfile.tilt) is an alternative that runs the same components inside a local k3d/kind cluster.

Running tests

Argo CD has three layers of automated tests:

1. Unit tests — colocated with the code under each package. Run with make test or go test ./.... State is mocked via pkg/.../mocks/ directories generated by mockery (config: .mockery.yaml).
2. End-to-end tests — test/e2e/ exercises the running components against a real Kubernetes cluster. They are gated by env vars defined in test/fixture/.
3. UI tests — ui-test/ contains Playwright/Cypress-style flows; the React side also has Jest unit tests under ui/src/.

The CI pipeline that runs all of this lives in .github/workflows/ci-build.yaml.

Common workflows

• Edit Go code → make lint && make test.
• Edit API/CRD structs in pkg/apis/application/v1alpha1/ → make codegen then make manifests to regenerate generated.pb.go, OpenAPI, install YAMLs.
• Edit UI → run pnpm start inside ui/ for a hot-reloading dev server, or use the ui line in the Procfile.
• Add a CLI subcommand → register it in cmd/argocd/commands/root.go, follow the patterns and conventions.

For the full PR checklist enforced by upstream, see AGENTS.md at the repo root.