Skip to content
Tutorials Center
My learning

Topics

Lesson 14 of 37 ยท Applications and Projects

Argo CD Repositories and Credentials: HTTPS, SSH, Apps and Templates

Connect private Git, Helm and OCI repositories to Argo CD with HTTPS tokens, SSH keys or a GitHub App, use credential templates for many repos, and manage repository secrets declaratively.

Public repositories need no setup, but real configuration repositories are private. Argo CD stores repository connections as Kubernetes Secrets in its namespace. This lesson shows the supported credential types, how to declare them without leaking secrets and how to troubleshoot "authentication required" errors.

The commands and YAML are read-only here, and every credential shown is a placeholder. The runnable blocks are stand-ins: a URL-to-credential matcher and a secret-leak scanner. Never paste real tokens into any web page.

Ways to authenticate

Method Typical use Fields
HTTPS with token GitHub, GitLab, Bitbucket url, username, password (a personal or deploy token)
SSH key Any Git server over SSH url (ssh form), sshPrivateKey
GitHub App Organizations (higher rate limits, no personal accounts) githubAppID, githubAppInstallationID, githubAppPrivateKey
TLS client certificate Self-hosted servers tlsClientCertData, tlsClientCertKey
OCI / Helm repo credentials Private chart registries type: helm, enableOCI, username and password

Prefer read-only deploy keys or fine-grained tokens limited to the config repository. Argo CD only needs to read.

Adding a repository with the CLI

Terminal
argocd repo add https://github.com/example/config.git \
  --username argocd-bot --password "$GIT_TOKEN"

argocd repo add [email protected]:example/config.git \
  --ssh-private-key-path ~/.ssh/argocd_deploy_key

argocd repo add https://charts.example.com --type helm --name internal \
  --username bot --password "$CHART_TOKEN"

argocd repo list

The environment variable is expanded by your shell, so the secret does not appear in the command text, though it can still be visible to the shell process. Prefer the declarative form for anything permanent.

Declarative repository Secrets

Argo CD discovers repositories from Secrets labelled argocd.argoproj.io/secret-type: repository:

YAML
apiVersion: v1
kind: Secret
metadata:
  name: config-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://github.com/example/config.git
  username: argocd-bot
  password: <token from your secret manager>

Do not commit that file with a real token. Instead create it from a secret manager (External Secrets Operator, Sealed Secrets, SOPS) so Git only contains an encrypted or referenced form. Secrets management for GitOps is its own topic in the security chapter.

Credential templates

If you have fifty repositories under one organization, registering each is tedious. A credential template matches by URL prefix:

YAML
apiVersion: v1
kind: Secret
metadata:
  name: example-org-creds
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repo-creds
stringData:
  type: git
  url: https://github.com/example
  githubAppID: "123456"
  githubAppInstallationID: "7890123"
  githubAppPrivateKey: |
    <placeholder, injected from a secret manager>

Any repository whose URL starts with https://github.com/example uses these credentials, unless a more specific repository Secret exists.

Stand-in: which credential applies?

This model picks the credential for a repository URL: an exact repository Secret first, else the longest matching template prefix.

JS Stand-in: credential matcher

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Host keys and certificates

For SSH, Argo CD must know the server's host key, or it refuses to connect (this prevents man-in-the-middle attacks). The argocd-ssh-known-hosts-cm ConfigMap already includes GitHub, GitLab and Bitbucket; add your own with argocd cert add-ssh --batch (feed it ssh-keyscan output after verifying the fingerprints). For HTTPS servers with a private certificate authority, add it with argocd cert add-tls or the argocd-tls-certs-cm ConfigMap rather than using --insecure-skip-server-verification.

Commit signature verification

Projects can require signed commits (signatureKeys in the AppProject, GPG keys registered with argocd gpg add). A sync is refused if the target revision is not signed by an allowed key. It is an additional guard against someone pushing to the repository with stolen credentials.

Stand-in: scan manifests for leaked secrets

The most common GitOps accident is committing a token. This simple scanner flags suspicious lines in files before you commit. Real scanners (gitleaks, trufflehog) are far more thorough.

JS Stand-in: secret scanner

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Troubleshooting

  • "authentication required" or "repository not found": the token lacks access, the URL differs from the one in the Application (trailing .git and http versus https matter for matching), or the credentials were stored for a different URL prefix.
  • "x509: certificate signed by unknown authority": add the CA certificate to Argo CD.
  • "knownhosts: key is unknown": add the SSH host key.
  • Rate limits on GitHub: use a GitHub App rather than a personal token.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Kubernetes label makes a Secret a repository connection for Argo CD?

    Argo CD discovers repository and credential Secrets by this label on Secrets in its namespace.
  2. 2. What is the benefit of a credential template (repo-creds)?

    Templates match by URL prefix, avoiding one Secret per repository.
  3. 3. Why prefer a GitHub App over a personal access token for an organization?

    App credentials are independent of any employee and get higher API limits.
  4. 4. Where should real tokens for repository Secrets come from in a GitOps setup?

    Committing plain tokens leaks them; use External Secrets, Sealed Secrets or SOPS.

Summary

  • Argo CD stores repository connections as labelled Secrets in its namespace.
  • Use read-only tokens, deploy keys or a GitHub App; avoid personal tokens.
  • Credential templates match by URL prefix; an exact repository Secret wins.
  • Configure SSH host keys and CA certificates instead of disabling verification.
  • Never commit raw secrets; feed Secrets from a secret manager.

Next: Sync Policies