TLS and repository credentials
Argo CD holds credentials to every repository it deploys from, and the credentials of every cluster it deploys to. Two trust relationships need to be right: clients must be able to trust Argo CD’s own endpoint, and Argo CD must be able to trust the Git servers it pulls from and authenticate to them with the least privilege that works.
TLS for the Argo CD server
Section titled “TLS for the Argo CD server”argocd-server serves the UI, the CLI, and the API over TLS. The behavior depends on whether TLS is turned off with the server.insecure parameter, as covered in installation and access.
| State | Behavior |
|---|---|
server.insecure: "true" | Plain HTTP. Used when a gateway or ingress terminates TLS in front of Argo CD |
| Insecure not set, no certificate supplied | Argo CD generates a self-signed certificate at startup and stores it in argocd-secret. Browsers and CLIs report it as untrusted |
Certificate supplied in argocd-server-tls | Argo CD serves that certificate |
A static certificate is the fix for the third case. argocd-server picks the certificate in this order: the argocd-server-tls Secret, then the deprecated tls.crt and tls.key keys in argocd-secret, then a generated one.
Supplying a certificate
Section titled “Supplying a certificate”When a private certificate authority signs the certificate, concatenate the server certificate and the CA certificate into one chain file, so clients receive the complete path:
cat argocd.crt root.crt > argocd-fullchain.crt
kubectl create -n argocd secret tls argocd-server-tls \ --cert=argocd-fullchain.crt \ --key=argocd.keyClients that trust the root CA now trust every certificate it issues, so renewals do not break anything. argocd-server watches the Secret and loads a new certificate without a restart, which also makes it a good target for cert-manager. The certificate must include the external hostname in its subject alternative names.
Two parameters narrow what the server offers: --tlsminversion (default 1.2) and --tlsciphers.
Terminating TLS at the gateway
Section titled “Terminating TLS at the gateway”Most installations keep server.insecure: "true" and let the gateway hold the public certificate. That is the simplest layout, but traffic between gateway and Pod is plain HTTP inside the cluster.
For TLS all the way to the Pod, leave the server in its secure mode and make the gateway forward encrypted traffic without terminating it. Removing the insecure setting while the gateway still speaks plain HTTP to the backend causes an endless redirect, because Argo CD answers every plain request with a redirect to HTTPS.
- Gateway API - use a
TLSRoutewith a TLS passthrough listener. See Gateway API. - ingress-nginx - enable the controller flag
--enable-ssl-passthroughand annotate the Ingress withnginx.ingress.kubernetes.io/ssl-passthrough: "true". The ingress-nginx project is archived, so prefer the Gateway API for new work. - Re-encrypt - terminate at the gateway and open a new TLS connection to the backend, which needs the gateway to trust the backend certificate.
TLS between Argo CD components
Section titled “TLS between Argo CD components”Three internal endpoints use TLS as well:
| Component | Secret | Reloads on change |
|---|---|---|
argocd-server | argocd-server-tls | Yes |
argocd-repo-server | argocd-repo-server-tls | No, restart required |
argocd-dex-server | argocd-dex-server-tls | No, restart required |
By default each of them generates a self-signed certificate and the callers do not validate it. That protects against eavesdropping but not against an impersonator inside the cluster network. To validate, give the repo server a persistent certificate (SANs argocd-repo-server and argocd-repo-server.argocd.svc), restart it, and start the callers (argocd-server, the application controller, the ApplicationSet controller) with --repo-server-ca-cert-path pointing at the CA. The notifications controller uses --argocd-repo-server-ca-cert-path. The older --repo-server-strict-tls flag is deprecated. With a service mesh that already encrypts pod-to-pod traffic, the plaintext flags turn the internal TLS off.
Trusting private Git servers
Section titled “Trusting private Git servers”A repository on a server whose certificate comes from a private CA fails with an unknown authority error, because Argo CD’s repo server only trusts the system certificate store. Applications sourcing from it show a comparison error such as Failed to load target state: failed to generate manifest for source 1 of 1. Well-known public CAs, including Let’s Encrypt, need no setup.
Register the server’s certificate, or better its CA chain. The key is the hostname only, not the URL:
argocd cert add-tls git.example.com --from git-fullchain.crtargocd cert listargocd cert rm git.example.comThe same data lives in the argocd-tls-certs-cm ConfigMap, which fits a GitOps workflow:
apiVersion: v1kind: ConfigMapmetadata: name: argocd-tls-certs-cm namespace: argocd labels: app.kubernetes.io/part-of: argocddata: git.example.com: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----In the UI the same function is at Settings, Repository certificates and known hosts, Add TLS Certificate. Certificates apply per server, not per repository, and one hostname can hold several certificates to cover a rollover. Changes reach the Pods through a volume mount, so allow a short delay.
Repository authentication
Section titled “Repository authentication”Credentials are Kubernetes Secrets in the Argo CD namespace with the label argocd.argoproj.io/secret-type: repository. The UI and CLI create the same Secrets, so every method below can be moved into Git.
An unauthenticated attempt against a protected repository ends with the message authentication required.
HTTPS with a username and password or token
Section titled “HTTPS with a username and password or token”argocd repo add https://git.example.com/org/config.git \ --username argocd-reader --password '<token>'Use a personal or project access token instead of a user password where the platform supports it. A token has its own lifecycle, can be scoped to chosen repositories, and can be limited to read-only access, so a leak costs less. The CLI tests the connection before saving, while the UI saves first and reports the result. The connect dialog also accepts a TLS client certificate for mutual TLS, and a project to scope the credential to. Some Git hosts redirect repository URLs that lack .git, and Argo CD does not follow redirects, so include the suffix when the host requires it.
apiVersion: v1kind: Secretmetadata: name: repo-config namespace: argocd labels: argocd.argoproj.io/secret-type: repositorystringData: type: git url: https://git.example.com/org/config.git username: argocd-reader password: <token> project: team-a # optional, restricts the credential to one projectSSH keys and deploy keys
Section titled “SSH keys and deploy keys”SSH uses a key pair. The public key is registered with the Git server and the private key goes to Argo CD. Argo CD cannot use a key protected by a passphrase, so generate one without it:
Attaching the public key to a user account gives Argo CD every repository that user can reach. A deploy key is a public key registered on a single repository, usually read-only, which keeps the blast radius to that repository. Register one per repository with the Git host’s Deploy keys setting, and give Argo CD the private half:
--ssh-private-key-path ./argocd_sshstringData: type: git sshPrivateKey: | -----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY-----Ingress controllers normally expose only ports 80 and 443, so a self-hosted Git server’s SSH port is often reached through its in-cluster Service address instead. For a non-default port, write the URL as ssh://git@host:2222/org/config.git, since the git@host:path form treats a port as part of the path.
SSH known hosts
Section titled “SSH known hosts”SSH requires the client to verify the server’s host key, and Argo CD has no trust-on-first-use. Without the host key, even a correct key pair fails to connect. Unlike TLS, there is no system store to fall back on, so every SSH server must be registered.
ssh-keyscan git.example.com | argocd cert add-ssh --batchThe entries are stored in the argocd-ssh-known-hosts-cm ConfigMap, in a single ssh_known_hosts key in the standard known_hosts format. Argo CD ships with the host keys of GitHub, GitLab, Bitbucket, and Azure DevOps already in it.
Other credential types
Section titled “Other credential types”The same Secret format covers GitHub Apps (githubAppID, githubAppInstallationID, githubAppPrivateKey), Google Cloud Source repositories, Azure service principals and workload identity, and Helm or OCI registries. A GitHub App avoids tying a credential to a person, and its tokens are short-lived.
Credential templates
Section titled “Credential templates”Registering credentials per repository does not scale to hundreds of repositories. A credential template holds one set of credentials for a URL prefix. Every repository under that prefix with no credentials of its own uses it.
apiVersion: v1kind: Secretmetadata: name: org-repo-creds namespace: argocd labels: argocd.argoproj.io/secret-type: repo-credsstringData: type: git url: https://git.example.com/org # prefix, not a full repository URL username: argocd-reader password: <token>argocd repocreds add https://git.example.com/org --username argocd-reader --password '<token>'argocd repo add https://git.example.com/org/config.git # picks up the templateIn the UI, fill in the connect dialog with the prefix URL and choose Save as credential template.
Two rules decide which credentials win:
- A repository with its own credentials never uses a template, even if the prefix matches. A repository added with a wrong password therefore fails, instead of falling back to a working template.
- When several templates match, the longest prefix wins, regardless of definition order.
The Secret label for a template is repo-creds, where a plain repository uses repository.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
ERR_TOO_MANY_REDIRECTS after enabling Argo CD TLS | The gateway sends plain HTTP to a server that now expects HTTPS | Pass TLS through, re-encrypt, or set server.insecure again |
| Browser or CLI says the Argo CD certificate is untrusted | The server uses its generated self-signed certificate | Provide argocd-server-tls signed by a CA the clients trust |
x509: certificate signed by unknown authority when adding a repository | The Git server uses a private CA | argocd cert add-tls <host> with the CA chain |
authentication required | No credentials, expired token, or wrong username | Add or update the repository credentials, using --upsert to overwrite |
| SSH repository connect fails with host key verification | The server’s host key is not in argocd-ssh-known-hosts-cm | Run ssh-keyscan and add it with argocd cert add-ssh |
| SSH key is rejected | The key has a passphrase, or the deploy key is on the wrong repository | Generate a key without a passphrase and register it on the right repository |
| Repository redirects with HTTP 301 | The URL lacks the .git suffix the host requires | Use the .git URL |
| A new repository does not pick up the template | The URL prefix does not match, or the repository has its own credentials | Check the prefix, and remove credentials from the repository entry |