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

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. 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) creates a repository entry and stores it as a cluster secret.

Public Git repository (HTTPS):

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

Private Git repository (SSH):

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:

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:

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 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 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, with additional settings handling in 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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}