Contributors Quick-Start¶

This guide is a starting point for first-time contributors running Argo CD locally for the first time.

It skips advanced topics such as codegen, which are covered in the running locally guide and the toolchain guide.

Getting Started¶

Prerequisites¶

Before starting, ensure you have the following tools installed with the specified minimum versions:

Git (v2.0.0+)
Go (version specified in go.mod - check with go version)
Docker (v20.10.0+) Or Podman (v3.0.0+)
Kind (v0.11.0+) Or Minikube (v1.23.0+)
Yarn (v1.22.0+)
Goreman (latest version)

Fork and Clone the Repository¶

Fork the Argo CD repository to your personal GitHub Account

Clone the forked repository:

git clone https://github.com/YOUR-USERNAME/argo-cd.git

Please note that the local build process uses GOPATH and that path should not be used, unless the Argo CD repository was directly cloned in it.

Add the upstream remote for rebasing:

cd argo-cd
git remote add upstream https://github.com/argoproj/argo-cd.git

Install Required Tools¶

Install development tools:

make install-go-tools-local
make install-codegen-tools-local

Install Go¶

https://go.dev/doc/install/

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

Install Docker or Podman¶

Installation guide for docker:¶

https://docs.docker.com/engine/install/

Installation guide for podman:¶

https://podman.io/docs/installation

Install or Upgrade a Tool for Running Local Clusters (e.g. kind or minikube)¶

Installation guide for kind:¶

https://kind.sigs.k8s.io/docs/user/quick-start/

Installation guide for minikube:¶

https://minikube.sigs.k8s.io/docs/start/

Start Your Local Cluster¶

For example, if you are using kind:

kind create cluster

Or, if you are using minikube:

minikube start

Or, if you are using minikube with podman driver:

minikube start --driver=podman

Install Argo CD¶

kubectl create namespace argocd &&
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/install.yaml

Set kubectl config to avoid specifying the namespace in every kubectl command.
All following commands in this guide assume the namespace is already set.

kubectl config set-context --current --namespace=argocd

Install `yarn`¶

https://classic.yarnpkg.com/lang/en/docs/install/

Install `goreman`¶

https://github.com/mattn/goreman#getting-started

Run Argo CD¶

cd argo-cd
make start-local ARGOCD_GPG_ENABLED=false

By default, Argo CD uses Docker. To use Podman instead, set the DOCKER environment variable to podman before running the make command:

cd argo-cd
DOCKER=podman make start-local ARGOCD_GPG_ENABLED=false

Navigate to localhost:4000 in your browser to load the Argo CD UI
It may take a few minutes for the UI to be responsive

Note

If the UI is not working, check the logs from make start-local. The logs are DEBUG level by default. If the logs are too noisy to find the problem, try editing log levels for the commands in the Procfile in the root of the Argo CD repo.

Common Make Targets¶

Here are some frequently used make targets (all will run on your machine):

Local Toolchain Make Targets¶

make build-local - Build Argo CD binaries
make test-local - Run unit tests
make codegen-local - Re-generate auto generated Swagger and Protobuf (after changing API code)
make lint-local - Run linting
make pre-commit-local - Run pre-commit checks
make start-e2e-local - Start server for end-to-end tests
make test-e2e-local - Run end-to-end tests
make serve-docs-local - Serve documentation
make start-local - Start Argo CD

Virtualized Toolchain Make Targets¶

make build - Build Argo CD binaries
make test - Run unit tests
make codegen - Re-generate auto generated Swagger and Protobuf (after changing API code)
make lint - Run linting
make pre-commit - Run pre-commit checks
make start-e2e - Start server for end-to-end tests
make test-e2e - Run end-to-end tests
make serve-docs - Serve documentation
make start - Start Argo CD

Making Changes¶

Before Submitting a PR¶

Rebase your branch against upstream main:

git fetch upstream
git rebase upstream/main

Run pre-commit checks:
```
make pre-commit-local
```

Docs Changes¶

Modifying the docs auto-reloads the changes on the documentation website that can be locally built using make serve-docs command. Once running, you can view your locally built documentation on port 8000.

UI Changes¶

Modifying the User-Interface (by editing .tsx or .scss files) auto-reloads the changes on port 4000.

Backend Changes¶

Modifying the API server, repo server, or a controller requires restarting the current make start-local session to reflect the changes.

CLI Changes¶

Modifying the CLI requires restarting the current make start-local session to reflect the changes.

To test most CLI commands, you will need to log in.

First, get the auto-generated secret:

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo

Then log in using that password and username admin:

dist/argocd login localhost:8080

Congrats on making it to the end of this runbook! 🚀

For more on Argo CD, find us in Slack - https://slack.cncf.io/ #argo-contributors