Skip to main content

​
Required Tools

You’ll need these tools installed with the specified minimum versions:

Git

v2.0.0+

Go

Version from go.mod

Docker/Podman

v20.10.0+ / v3.0.0+

Kubernetes Cluster

Kind, Minikube, or K3d

​
Installation Steps

​
Install Git

You’ll need a Git client for pulling source code and pushing changes.

Git Installation Guide

Official Git installation instructions

​
Install Go

1

Download Go SDK

Visit the official Go download page and install Go.
2

Match go.mod Version

Install Go with a version equal to or greater than the version listed in go.mod.
3

Verify Installation

go version
We assume your Go workspace is at ~/go.

​
Install Docker or Podman

Install Docker following the official documentation.Argo CD uses multi-stage builds, so you’ll need a working Docker runtime environment.Verify installation:
docker version

​
Install a Local Kubernetes Cluster

You’ll need a local Kubernetes cluster for development. Choose one:
Installation: Kind Quick StartStart the cluster:
kind create cluster
Kind runs Kubernetes inside Docker containers, making it lightweight and fast.
Verify cluster installation: 
kubectl version

​
Fork and Clone the Repository

1

Fork the Repository

Fork the Argo CD repository to your personal GitHub account.
2

Clone Your Fork

git clone https://github.com/YOUR-USERNAME/argo-cd.git
The local build process uses GOPATH. Don’t clone the repository directly into your GOPATH unless intended.
3

Add Upstream Remote

Create a remote pointing to the original repository for easy updates:
cd argo-cd
git remote add upstream https://github.com/argoproj/argo-cd.git
Keep your local branches up-to-date:
git pull upstream master

​
Install Development Tools

Install required Go tools and code generation tools: 
make install-go-tools-local
make install-codegen-tools-local

​
Install Argo CD on Your Cluster

Deploy Argo CD to your local cluster: 
kubectl create namespace argocd && \
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/install.yaml
Set default namespace: 
kubectl config set-context --current --namespace=argocd

​
Toolchain Options

Argo CD provides two development toolchains:

​
Virtualized Toolchain

The virtualized toolchain runs builds and tests inside Docker containers using the test tools image. This provides:
  • Same runtime environment as production
  • Easy to keep up-to-date
  • Repeatable builds
Requirements:
  • Your Kubernetes API server must listen on your local machine interface (not 127.0.0.1 only)
  • Your ~/.kube/config must not use localhost, 127.0.0.1, or 0.0.0.0
Build the test tools image:
make test-tools-image
Using Podman instead of Docker:
DOCKER=podman make start
Test cluster connectivity:
make verify-kube-connect

​
Local Toolchain

The local toolchain provides a faster development cycle, especially on macOS where Docker runs in a VM.Additional requirements:Install tools:
BIN=~/go/bin make install-tools-local
Set BIN=~/go/bin and add ~/go/bin to your PATH to avoid requiring root privileges.

​
Next Steps

Running Locally

Start Argo CD services locally

Tilt Development

Use Tilt for rapid development

Architecture

Understand the component architecture

Contributing

Learn how to contribute code

​
Troubleshooting

If you see errors like “connection refused to 127.0.0.1:6443”:
  1. Edit your ~/.kube/config
  2. Replace 127.0.0.1 or localhost with your machine’s IP address
  3. For K3d, follow the specific network configuration steps
If your user lacks Docker privileges:
SUDO=sudo make start
Or export permanently:
export SUDO=sudo
Minikube with the Docker driver is not compatible with the virtualized toolchain because it hard-codes the API server to 127.0.0.1.Start Minikube with embedded certificates:
minikube start --embed-certs