Commit signing and sync impersonation
Two controls limit how much a compromised input can hurt. Commit signature verification checks that the manifests Argo CD is about to apply were committed by someone you trust. Sync impersonation checks the other end: even a trusted manifest can only change what the service account assigned to its destination is allowed to change.
Verifying signed commits
Section titled “Verifying signed commits”Argo CD deploys whatever Git contains. If an attacker can push a commit, through a stolen token or a compromised contributor account, the change reaches the cluster on the next sync. Signed commits tie each change to a key you chose to trust. Argo CD can refuse to sync from a revision that is not signed by one of those keys.
Verification uses GnuPG and applies to Git sources only. Helm and OCI sources are not covered. Argo CD’s trust model is simple: any public key you import is trusted. It does not evaluate key signatures or a web of trust.
Step 1: import public keys
Section titled “Step 1: import public keys”Argo CD keeps a keyring of GnuPG public keys. Export a key in ASCII-armored form and import it:
argocd gpg add --from public.pgpargocd gpg listargocd gpg get <key-id>argocd gpg rm <key-id>The UI offers the same under Settings, GnuPG keys, and it accepts only ASCII-armored keys. Declaratively, keys are entries in the argocd-gpg-keys-cm ConfigMap, named by key ID with the armored key as the value. Managing the keyring needs the gpgkeys RBAC resource with get, create, or delete. The keyring in each repo server Pod is rebuilt from the ConfigMap on every restart, so never edit it by hand.
Step 2: add a policy to the AppProject
Section titled “Step 2: add a policy to the AppProject”Enforcement belongs to the project, so it covers every Application in it. Policies sit under spec.sourceIntegrity.git.policies. Each policy matches repositories by URL glob and names the keys to trust:
apiVersion: argoproj.io/v1alpha1kind: AppProjectmetadata: name: team-a namespace: argocdspec: sourceIntegrity: git: policies: - repos: - url: "https://git.example.com/team-a/*" - url: "!https://git.example.com/team-a/sandbox.git" # leading ! excludes a match gpg: mode: head # none, head, or strict keys: - "D56C4FCA57A46444" # key IDs imported in step 1Only one policy applies to a repository, and a repository that matches no policy is not verified. A multi-source Application checks each source against its own policy. The UI does not edit these policies yet, so use manifests or the CLI.
| Mode | Verifies | Use when |
|---|---|---|
none | Nothing. Unsigned and invalid commits are accepted | A matching repository, such as a sandbox, is explicitly exempt from verification |
head | The commit the target revision points to. For an annotated tag, the tag’s signature, so the tag must be created with git tag -s | You trust the people with merge rights and want every deployed revision signed |
strict | The target revision and all of its ancestors | You need a signed history end to end |
When a revision does not meet the policy, the sync is blocked and the Application reports a comparison error that names the commit and the problem, for example signed with unallowed key or an unsigned revision. Signing a new commit with a trusted key and pushing it clears the error on the next refresh.
git config user.signingkey D56C4FCA57A46444git commit -S -am "Update manifests"git log --show-signature -1git pushSource integrity also blocks argocd app sync --local, because local files have no Git signature.
Seal commits
Section titled “Seal commits”strict mode is impractical when a repository already contains unsigned commits, or commits from keys that were later retired. Rewriting history with a rebase is risky. A seal commit avoids that. It is a signed, possibly empty commit that states you reviewed everything before it. Verification walks back only as far as the newest seal on each branch.
git commit --allow-empty --signoff --gpg-sign \ --trailer="Argocd-gpg-seal: all history before this commit reviewed" \ -m "Seal history"A seal can mean “we start signing commits now”, “I reviewed and approve the merged changes from this outside contributor”, or “I replaced my old signing key, and I trust the old key only before this commit”.
Migrating from signatureKeys
Section titled “Migrating from signatureKeys”Remove spec.signatureKeys and define a policy that reproduces the old behavior, which was head-only verification for every repository in the project:
spec: sourceIntegrity: git: policies: - repos: - url: "*" gpg: mode: head keys: - "<key ids from signatureKeys>"If a project defines only signatureKeys, Argo CD converts it internally, but the old field will be removed in a later release.
Turning verification off
Section titled “Turning verification off”GnuPG support is switched off for the whole installation by setting the environment variable ARGOCD_GPG_ENABLED to false on argocd-server, argocd-repo-server, argocd-application-controller, and argocd-applicationset-controller.
Sync impersonation
Section titled “Sync impersonation”By default a sync runs as the Argo CD application controller’s own service account. In a multi-tenant installation that account must hold the highest privilege any tenant needs. If one of ten Applications needs cluster-admin, the controller needs cluster-admin for all ten. Projects restrict what an Application may declare, but they are enforced inside Argo CD. A compromised control plane would hand an attacker those privileges.
With sync impersonation, the controller uses the Kubernetes impersonation mechanism to act as a service account chosen per destination. The Kubernetes API server then enforces that account’s RBAC on every create, update, and delete of the sync.
It applies to the lifecycle of resources an Application manages: creating, updating, and pruning during sync, deletion through the Application finalizer, and operations a user triggers from the UI.
Step 1: enable it
Section titled “Step 1: enable it”The switch is global. Once on, it applies to every Application on the instance:
apiVersion: v1kind: ConfigMapmetadata: name: argocd-cm namespace: argocd labels: app.kubernetes.io/part-of: argocddata: application.sync.impersonation.enabled: "true"By default impersonation is enforced: a sync fails if its project has no matching service account. For a gradual rollout, add application.sync.impersonation.enforced: "false". Argo CD then falls back to the controller’s service account when no mapping matches, which keeps old Applications working while you configure projects one by one. Turn enforcement back on at the end, because the fallback weakens isolation.
Step 2: map destinations to service accounts
Section titled “Step 2: map destinations to service accounts”Mappings live in the AppProject under spec.destinationServiceAccounts. Each entry names a cluster server, a namespace, and the service account to use there:
apiVersion: argoproj.io/v1alpha1kind: AppProjectmetadata: name: team-a namespace: argocdspec: sourceRepos: - "https://git.example.com/team-a/*" destinations: - server: https://kubernetes.default.svc namespace: "team-a-*" destinationServiceAccounts: - server: https://kubernetes.default.svc namespace: team-a-prod defaultServiceAccount: prod-deployer - server: https://kubernetes.default.svc namespace: team-a-dev defaultServiceAccount: dev-deployerDuring a sync, Argo CD takes the first entry that matches the server and namespace. If none matches and enforcement is on, the sync fails. A last entry with namespace: "*" and a low-privilege service account acts as a catch-all, but leaving it out forces every destination to be named explicitly.
A service account may carry its own namespace as tenant-ns:deployer. Without one, Argo CD uses the Application’s destination namespace, and if that is also empty, the Application’s namespace. The CLI manages the same list:
argocd proj add-destination-service-account team-a https://kubernetes.default.svc team-a-prod prod-deployerargocd proj remove-destination-service-account team-a https://kubernetes.default.svc team-a-prodStep 3: grant the service account only what it needs
Section titled “Step 3: grant the service account only what it needs”Argo CD does not create the service accounts. The platform team provisions the namespace, the service account, and a Role and RoleBinding that cover just the resource types the tenant should manage:
kubectl create namespace team-a-prodkubectl create serviceaccount prod-deployer -n team-a-prod
kubectl create role deployer -n team-a-prod \ --verb=get,list,watch,create,update,patch,delete \ --resource=deployments.apps,services,configmaps
kubectl create rolebinding deployer -n team-a-prod \ --role=deployer --serviceaccount=team-a-prod:prod-deployerA sync that touches anything outside that role fails at the Kubernetes API with a forbidden error naming the service account:
secrets "db-credentials" is forbidden: User "system:serviceaccount:team-a-prod:prod-deployer"cannot create resource "secrets" in API group "" in the namespace "team-a-prod"That error is the control working. A tenant cannot deploy Secrets, CRDs, or cluster-scoped objects unless their account is allowed to. Argo CD also still needs its own permissions to read and watch resources for health and diffing. Impersonation covers the write side.
Combining the two controls
Section titled “Combining the two controls”| Control | Protects against | Enforced by |
|---|---|---|
| Project policies and RBAC | Users deploying where they should not | Argo CD |
| Signature verification | Unreviewed or forged changes reaching Git | Argo CD |
| Sync impersonation | A trusted sync, or Argo CD itself, doing more than the tenant is entitled to | The Kubernetes API server |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Likely cause | Fix |
|---|---|---|
| Application is blocked with a comparison error about an unsigned revision | The target commit has no signature | Sign the commit and push, or point the Application at a signed revision |
| Error says the revision is signed with an unallowed key | The key ID is missing from the policy keys list | Add the key ID to the project policy |
| A signed commit is still rejected right after importing its key | The key has not reached every repo server Pod yet | Wait a moment, then restart argocd-repo-server if it persists |
strict mode fails on old history | Early commits are unsigned or signed by retired keys | Add a seal commit |
argocd app sync --local stops working | Source integrity forbids unsigned local files | Sync from Git, or relax the policy for that repository |
| Sync fails after enabling impersonation with no matching service account | The project has no destinationServiceAccounts entry for the destination | Add an entry or a catch-all, or set enforced to "false" during migration |
forbidden for a resource the Application declares | The deployer service account’s Role lacks it | Extend the Role if the tenant is meant to manage that kind |
| Sync cannot find the service account | The service account does not exist in the resolved namespace | Create it, or write the name as namespace:name |