Skip to content
Documentation Background

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.


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.

StateBehavior
server.insecure: "true"Plain HTTP. Used when a gateway or ingress terminates TLS in front of Argo CD
Insecure not set, no certificate suppliedArgo 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-tlsArgo 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.

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:

Terminal window
cat argocd.crt root.crt > argocd-fullchain.crt
kubectl create -n argocd secret tls argocd-server-tls \
--cert=argocd-fullchain.crt \
--key=argocd.key

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

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 TLSRoute with a TLS passthrough listener. See Gateway API.
  • ingress-nginx - enable the controller flag --enable-ssl-passthrough and annotate the Ingress with nginx.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.

Three internal endpoints use TLS as well:

ComponentSecretReloads on change
argocd-serverargocd-server-tlsYes
argocd-repo-serverargocd-repo-server-tlsNo, restart required
argocd-dex-serverargocd-dex-server-tlsNo, 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.


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:

Terminal window
argocd cert add-tls git.example.com --from git-fullchain.crt
argocd cert list
argocd cert rm git.example.com

The same data lives in the argocd-tls-certs-cm ConfigMap, which fits a GitOps workflow:

apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-tls-certs-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd
data:
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.


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”
Terminal window
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: v1
kind: Secret
metadata:
name: repo-config
namespace: argocd
labels:
argocd.argoproj.io/secret-type: repository
stringData:
type: git
url: https://git.example.com/org/config.git
username: argocd-reader
password: <token>
project: team-a # optional, restricts the credential to one project

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:

Terminal window
ssh-keygen -t ed25519 -f argocd_ssh -C "[email protected]" -q -N ""

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:

Terminal window
argocd repo add [email protected]:org/config.git \
--ssh-private-key-path ./argocd_ssh
stringData:
type: git
url: [email protected]:org/config.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 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.

Terminal window
ssh-keyscan git.example.com | argocd cert add-ssh --batch

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

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.


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: v1
kind: Secret
metadata:
name: org-repo-creds
namespace: argocd
labels:
argocd.argoproj.io/secret-type: repo-creds
stringData:
type: git
url: https://git.example.com/org # prefix, not a full repository URL
username: argocd-reader
password: <token>
Terminal window
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 template

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


SymptomLikely causeFix
ERR_TOO_MANY_REDIRECTS after enabling Argo CD TLSThe gateway sends plain HTTP to a server that now expects HTTPSPass TLS through, re-encrypt, or set server.insecure again
Browser or CLI says the Argo CD certificate is untrustedThe server uses its generated self-signed certificateProvide argocd-server-tls signed by a CA the clients trust
x509: certificate signed by unknown authority when adding a repositoryThe Git server uses a private CAargocd cert add-tls <host> with the CA chain
authentication requiredNo credentials, expired token, or wrong usernameAdd or update the repository credentials, using --upsert to overwrite
SSH repository connect fails with host key verificationThe server’s host key is not in argocd-ssh-known-hosts-cmRun ssh-keyscan and add it with argocd cert add-ssh
SSH key is rejectedThe key has a passphrase, or the deploy key is on the wrong repositoryGenerate a key without a passphrase and register it on the right repository
Repository redirects with HTTP 301The URL lacks the .git suffix the host requiresUse the .git URL
A new repository does not pick up the templateThe URL prefix does not match, or the repository has its own credentialsCheck the prefix, and remove credentials from the repository entry