Repository Connection Configuration

Configure Git repository connections for Argo CD using declarative YAML

Overview

Argo CD repository credentials are stored in Kubernetes Secrets with the label argocd.argoproj.io/secret-type: repository. This guide covers how to configure repository connections using HTTPS, SSH, GitHub Apps, and Google Cloud Source repositories.

Some Git hosters (notably GitLab) require you to specify the .git suffix in the repository URL, otherwise they will send a HTTP 301 redirect. Argo CD will not follow these redirects.

Repository Secret Structure

Each repository Secret must have:

• A url field containing the repository URL
• Authentication credentials (varies by connection type)
• Optional project field to scope credentials to a specific project
• The label argocd.argoproj.io/secret-type: repository

HTTPS Repositories

Connect to repositories using username and password authentication:

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/private-repo
  password: my-password
  username: my-username
  project: my-project

With Proxy Configuration

Specify proxy settings for repository access:

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/private-repo
  proxy: https://proxy-server-url:8888
  noProxy: ".internal.example.com,company.org,10.123.0.0/16"
  password: my-password
  username: my-username

Not all tools support the same noProxy syntax. If having issues, try using full domain names instead of wildcards or IP ranges.

SSH Repositories

Connect using SSH private keys:

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: [e-mail]:argoproj/my-private-repository.git
  sshPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----

See the Kubernetes documentation for instructions on creating a secret containing a private key.

GitHub App Authentication

Use GitHub Apps for repository access:

apiVersion: v1
kind: Secret
metadata:
  name: github-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/my-private-repository
  githubAppID: 1
  githubAppInstallationID: 2
  githubAppPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----

GitHub Enterprise

apiVersion: v1
kind: Secret
metadata:
  name: github-enterprise-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://ghe.example.com/argoproj/my-private-repository
  githubAppID: 1
  githubAppInstallationID: 2
  githubAppEnterpriseBaseUrl: https://ghe.example.com/api/v3
  githubAppPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...
    -----END OPENSSH PRIVATE KEY-----

Google Cloud Source Repositories

Authenticate using GCP service account keys:

apiVersion: v1
kind: Secret
metadata:
  name: gcp-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://source.developers.google.com/p/my-google-project/r/my-repo
  gcpServiceAccountKey: |
    {
      "type": "service_account",
      "project_id": "my-google-project",
      "private_key_id": "REDACTED",
      "private_key": "-----BEGIN PRIVATE KEY-----\nREDACTED\n-----END PRIVATE KEY-----\n",
      "client_email": "[e-mail]",
      "client_id": "REDACTED",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/argocd-service-account%40my-google-project.iam.gserviceaccount.com"
    }

Repository Credential Templates

Use credential templates to share the same credentials across multiple repositories. Credentials are applied to repositories with matching URL prefixes.

apiVersion: v1
kind: Secret
metadata:
  name: first-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/private-repo
---
apiVersion: v1
kind: Secret
metadata:
  name: second-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/argoproj/other-private-repo
---
apiVersion: v1
kind: Secret
metadata:
  name: private-repo-creds
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repo-creds
stringData:
  type: git
  url: https://github.com/argoproj
  password: my-password
  username: my-username

Matching credential template URL prefixes is done on a best match basis. The longest matching prefix takes precedence.

TLS Certificates

Configure custom TLS certificates for repositories using self-signed certificates or custom CAs in the argocd-tls-certs-cm ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-tls-certs-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-cm
    app.kubernetes.io/part-of: argocd
data:
  server.example.com: |
    -----BEGIN CERTIFICATE-----
    MIIF1zCCA7+gAwIBAgIUQdTcSHY2Sxd3Tq/v1eIEZPCNbOowDQYJKoZIhvcNAQEL
    ...
    -----END CERTIFICATE-----

The hostname part of the repository URL (e.g., server.example.com from https://server.example.com/repos/my-repo) is used as the key.

SSH Known Hosts

For SSH repositories, configure known host keys in the argocd-ssh-known-hosts-cm ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-ssh-known-hosts-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-ssh-known-hosts-cm
    app.kubernetes.io/part-of: argocd
data:
  ssh_known_hosts: |
    github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
    github.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=
    gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
    gitlab.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCsj2bNKTBSpIYDEGk9KxsGh3mySTRgMtXL583qmBpzeQ+jqCMRgBqB98u3z++J1sKlXHWfM9dyhSevkMwSbhoR8XIq/U0tCNyokEi/ueaBMCvbcTHhO7FcwzY92WK4Yt0aGROY5qX2UKSeOvuP4D6TPqKF1onrSzH9bx9XUf2lEdWT/ia1NEKjunUqu1xOB/StKDHMoX4/OKyIzuS0q/T1zOATthvasJFoPrAjkohTyaDUz2LN5JoH839hViyEG82yB+MjcFV5MU3N1l1QL3cVUCh93xSaua1N85qivl+siMkPGbO5xR/En4iEY6K2XPASUEMaieWVNTRCtJ4S8H+9

Generate keys using ssh-keyscan:

ssh-keyscan github.com >> ssh_known_hosts

Credential Fields Reference

SSH Repositories

• sshPrivateKey: SSH private key for authentication

HTTPS Repositories

• username: Username for authentication
• password: Password for authentication
• tlsClientCertData: TLS client certificate
• tlsClientCertKey: TLS client certificate private key

GitHub App Repositories

• githubAppPrivateKey: GitHub App private key
• githubAppID: GitHub Application ID
• githubAppInstallationID: Installation ID
• githubAppEnterpriseBaseUrl: Base API URL for GitHub Enterprise
• tlsClientCertData: TLS client certificate (for custom certs)
• tlsClientCertKey: TLS client certificate private key

Best Practices

Use Sealed Secrets

Consider using sealed-secrets to store encrypted Secret definitions as Kubernetes manifests.

Scope Credentials

Use the project field to limit repository credentials to specific Argo CD projects.

Credential Templates

Leverage credential templates to avoid duplicating credentials across multiple repositories.

Manage Certificates

Keep TLS certificates and SSH known hosts up to date in their respective ConfigMaps.