Skip to content
Documentation Background

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.


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.

Argo CD keeps a keyring of GnuPG public keys. Export a key in ASCII-armored form and import it:

Terminal window
gpg --armor --export [email protected] > public.pgp
argocd gpg add --from public.pgp
argocd gpg list
argocd 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.

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/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
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 1

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

ModeVerifiesUse when
noneNothing. Unsigned and invalid commits are acceptedA matching repository, such as a sandbox, is explicitly exempt from verification
headThe commit the target revision points to. For an annotated tag, the tag’s signature, so the tag must be created with git tag -sYou trust the people with merge rights and want every deployed revision signed
strictThe target revision and all of its ancestorsYou 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.

Terminal window
git config user.signingkey D56C4FCA57A46444
git commit -S -am "Update manifests"
git log --show-signature -1
git push

Source integrity also blocks argocd app sync --local, because local files have no Git signature.

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.

Terminal window
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”.

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.

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.


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.

The switch is global. Once on, it applies to every Application on the instance:

apiVersion: v1
kind: ConfigMap
metadata:
name: argocd-cm
namespace: argocd
labels:
app.kubernetes.io/part-of: argocd
data:
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/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
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-deployer

During 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:

Terminal window
argocd proj add-destination-service-account team-a https://kubernetes.default.svc team-a-prod prod-deployer
argocd proj remove-destination-service-account team-a https://kubernetes.default.svc team-a-prod

Step 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:

Terminal window
kubectl create namespace team-a-prod
kubectl 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-deployer

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

ControlProtects againstEnforced by
Project policies and RBACUsers deploying where they should notArgo CD
Signature verificationUnreviewed or forged changes reaching GitArgo CD
Sync impersonationA trusted sync, or Argo CD itself, doing more than the tenant is entitled toThe Kubernetes API server

SymptomLikely causeFix
Application is blocked with a comparison error about an unsigned revisionThe target commit has no signatureSign the commit and push, or point the Application at a signed revision
Error says the revision is signed with an unallowed keyThe key ID is missing from the policy keys listAdd the key ID to the project policy
A signed commit is still rejected right after importing its keyThe key has not reached every repo server Pod yetWait a moment, then restart argocd-repo-server if it persists
strict mode fails on old historyEarly commits are unsigned or signed by retired keysAdd a seal commit
argocd app sync --local stops workingSource integrity forbids unsigned local filesSync from Git, or relax the policy for that repository
Sync fails after enabling impersonation with no matching service accountThe project has no destinationServiceAccounts entry for the destinationAdd an entry or a catch-all, or set enforced to "false" during migration
forbidden for a resource the Application declaresThe deployer service account’s Role lacks itExtend the Role if the tenant is meant to manage that kind
Sync cannot find the service accountThe service account does not exist in the resolved namespaceCreate it, or write the name as namespace:name