# How to Integrate Argo CD with Git Repositories: CLI, UI, and Declarative Setup

> Integrate Argo CD with Git repositories for automatic manifest cloning and cluster state synchronization using Kubernetes secrets. Learn CLI, UI, and declarative setup.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: how-to-guide
- Published: 2026-07-14

---

**Argo CD integrates with Git repositories by storing connection details and credentials as Kubernetes secrets of type `argoproj.io/secret-type=repository`, enabling the repo-server to clone manifests and synchronize cluster state automatically.**

Argo CD follows the GitOps paradigm by pulling application manifests directly from Git repositories rather than pushing changes from CI pipelines. To establish this connection, administrators must register repositories and configure authentication methods that allow the Argo CD repo-server to access private or public source code in `argoproj/argo-cd`. Whether you manage a single cluster or a multi-tenant environment, understanding how to integrate Argo CD with Git repositories securely is essential for automated continuous delivery.

## Registering Git Repositories in Argo CD

Argo CD represents repository configurations using the `Repository` struct defined in [`pkg/apis/application/v1alpha1/repository_types.go`](https://github.com/argoproj/argo-cd/blob/main/pkg/apis/application/v1alpha1/repository_types.go). You can register repositories through three primary interfaces: the CLI, the Web UI, or declarative Kubernetes secrets.

### Using the Argo CD CLI

The `argocd repo add` command (documented in [`docs/user-guide/commands/argocd_repo_add.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/commands/argocd_repo_add.md)) creates a repository entry and stores it as a cluster secret.

**Public Git repository (HTTPS):**

```bash
argocd repo add https://github.com/argoproj/argocd-example-apps.git \
  --type git \
  --project default

```

**Private Git repository (SSH):**

```bash
argocd repo add git@github.com:myorg/my-private-app.git \
  --ssh-private-key-path ~/.ssh/id_rsa \
  --insecure-ignore-host-key   # only for testing

```

**GitHub App authentication:**

```bash
argocd repo add https://github.com/argoproj/argocd-example-apps.git \
  --github-app-id 123 \
  --github-app-installation-id 456 \
  --github-app-private-key-path ./gh-app.key

```

### Using the Web UI

Navigate to **Settings → Repositories** and click **+ Connect Repo**. Choose **VIA HTTPS** or **VIA SSH**, enter the repository URL, and paste the appropriate credential (username/password, personal access token, or private key). You can optionally tick **Save as credential template** to reuse the same credentials for other repositories sharing the same URL prefix, reducing repetitive configuration.

### Declarative Setup via Kubernetes Secrets

For GitOps-style management of Argo CD itself, declare repositories as secrets in the `argocd` namespace with the specific label `argocd.argoproj.io/secret-type: repository`, as shown in [`operator-manual/declarative-setup.md`](https://github.com/argoproj/argo-cd/blob/main/operator-manual/declarative-setup.md):

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: helm-private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: helm
  url: contoso.azurecr.io/charts
  name: contosocharts
  enableOCI: "true"
  useAzureWorkloadIdentity: "true"

```

## Configuring Authentication Methods

Argo CD supports multiple credential mechanisms defined in [`docs/user-guide/private-repositories.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/private-repositories.md) to accommodate different security requirements and Git providers.

### HTTPS with Username/Password or Tokens

For private repositories accessed over HTTPS, provide a **username** and **password** (often a personal access token) when running `argocd repo add`. Argo CD stores these credentials in the repository secret and uses them for HTTP Basic authentication during clone operations.

### SSH Private Key Authentication

SSH authentication requires the `--ssh-private-key-path` flag pointing to a PEM-encoded private key. The repo-server supports SSH-style URLs (`git@github.com:org/repo.git`) or explicit `ssh://` protocols with optional port specifications. For testing environments only, you may use `--insecure-ignore-host-key` to bypass host key verification, though this is not recommended for production.

### GitHub App Credentials

For GitHub Cloud or GitHub Enterprise, authenticate using **GitHub App** credentials instead of personal tokens. Specify `--github-app-id`, `--github-app-installation-id`, and `--github-app-private-key-path` during registration. This method provides enhanced security through short-lived tokens and centralized access control.

### TLS Client Certificates

When connecting to HTTPS servers that require mutual TLS, configure **TLS client certificates** using the appropriate CLI flags or secret fields. This enables Argo CD to present a client certificate during the TLS handshake, verifying identity to the Git server.

## Repository Scoping and RBAC

You can scope a repository to a specific Argo CD project by adding the `--project <project-name>` flag during registration. Project-scoped repositories enable fine-grained **RBAC** and isolation, ensuring that only applications within the designated project can access the repository. This pattern is documented in [`docs/user-guide/projects.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/projects.md) and is critical for multi-tenant clusters where teams must not access each other's source code.

## Internal Implementation and Repo-Server Behavior

Internally, repository definitions are represented by the `Repository` Go struct located in [`pkg/apis/application/v1alpha1/repository_types.go`](https://github.com/argoproj/argo-cd/blob/main/pkg/apis/application/v1alpha1/repository_types.go), with additional settings handling in [`util/settings/settings.go`](https://github.com/argoproj/argo-cd/blob/main/util/settings/settings.go). The **repo-server** component reads these secrets to execute `git clone` operations, supporting shallow clones (`--depth`) for performance optimization and automatically handling **Git submodules** (enabled by default) as detailed in [`docs/user-guide/private-repositories.md`](https://github.com/argoproj/argo-cd/blob/main/docs/user-guide/private-repositories.md).

## Summary

- **Register repositories** via the CLI (`argocd repo add`), Web UI (**Settings → Repositories**), or declarative Kubernetes secrets with the label `argocd.argoproj.io/secret-type: repository`.
- **Choose authentication** appropriate for your Git provider: HTTPS tokens, SSH private keys, GitHub App credentials, or TLS client certificates.
- **Scope repositories** to specific projects using the `--project` flag to enforce RBAC boundaries in multi-tenant environments.
- **Credentials are stored** as Kubernetes secrets and consumed by the repo-server to perform clone operations with support for submodules and shallow clones.

## Frequently Asked Questions

### How does Argo CD store repository credentials securely?

Argo CD stores repository credentials as Kubernetes secrets in the `argocd` namespace with the label `argocd.argoproj.io/secret-type: repository`. According to the source code in [`pkg/apis/application/v1alpha1/repository_types.go`](https://github.com/argoproj/argo-cd/blob/main/pkg/apis/application/v1alpha1/repository_types.go), these secrets contain fields for URLs, SSH keys, passwords, and TLS certificates, which the repo-server retrieves during Git operations.

### Can I use the same credentials for multiple Git repositories?

Yes. When adding a repository via the Web UI, tick **Save as credential template** to create a credential template. Argo CD will automatically apply these credentials to any repository matching the URL prefix without requiring individual registration, streamlining management for organizations with many repositories under the same provider.

### Does Argo CD support Git submodules?

Yes, Git submodule handling is enabled by default in Argo CD. The repo-server recursively initializes and updates submodules when cloning a repository, ensuring that manifest files referencing external Helm charts or Kustomize bases located in submodules are correctly resolved during the synchronization process.

### How do I troubleshoot repository connection failures in Argo CD?

First, verify the repository secret exists in the `argocd` namespace and contains the correct URL and credentials. Check the repo-server logs for specific Git errors such as authentication failures or host key mismatches. For SSH issues, ensure the private key format is PEM-encoded and that the corresponding public key is registered with your Git provider. Use `argocd repo list` to verify connection status and `argocd repo get <url>` to inspect detailed error messages.