StackPractices
intermediate By Mathias Paulenko

Complete Guide to GitOps with ArgoCD

Deploy Kubernetes apps with GitOps and ArgoCD: installation, ApplicationSets, sync strategies, Helm/Kustomize, RBAC, and multi-cluster.

Introduction

GitOps uses Git as the single source of truth for infrastructure and application deployment. ArgoCD is a Kubernetes-native continuous delivery tool built on GitOps — it watches a Git repository and syncs the desired state to Kubernetes clusters. The following guide covers installation, application configuration, sync strategies, Helm/Kustomize integration, RBAC, and multi-cluster management.

The model inverts the classic push pipeline: instead of CI deploying to the cluster with kubectl apply, a controller inside the cluster pulls desired state from Git and reconciles it continuously. CI’s job shrinks to “build image, update manifest, open PR” — the deploy step is gone, along with the credentials that made it possible.

GitOps loop with ArgoCD: CI pushes manifests to Git, ArgoCD polls the repo, diffs desired vs live state, and syncs to the cluster.

GitOps Principles

  1. Declarative: System state is described declaratively in Git — manifests, Helm values, Kustomize overlays, not imperative scripts
  2. Versioned: Git gives you versioning, history, and rollback — git revert is the rollback path
  3. Pulled: ArgoCD pulls changes from Git (no push from CI — the cluster credentials never leave the cluster)
  4. Continuously reconciled: ArgoCD detects drift and corrects it — manual kubectl edits get reverted when selfHeal is on

That last point is the one people underestimate: GitOps isn’t just “deploy on merge”. The controller watches live state too — someone kubectl edits a replica count at 2am, ArgoCD sees the drift and puts it back. Git stays the truth.

ArgoCD vs Flux

Both are CNCF GitOps operators, and the choice is real:

ArgoCDFlux
UI + RBAC + SSO built inCLI-first, UI via third parties (Weave GitOps, Headlamp)
Application CRD + ApplicationSetFluxCD Kustomization/HelmRelease CRDs
Multi-cluster out of the boxCluster API or custom wiring for multi-cluster
Notifications controller includedAlerting via notification-controller (webhooks)
Heavier footprint (several components)Lighter — runs as a small set of controllers

Teams with many namespaces and non-expert users usually pick ArgoCD for the UI; teams already fluent in Kubernetes internals who want minimal moving parts lean Flux. This guide is the ArgoCD deep-dive — for the side-by-side decision in a production workflow, see the GitOps production guide.

Installing ArgoCD

kubectl create namespace argocd
kubectl apply -n argocd \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Get admin password
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

# Port-forward to access UI
kubectl port-forward svc/argocd-server -n argocd 8080:443

For real deployments skip port-forward — put argocd-server behind an ingress with TLS, enable SSO (Dex/OIDC with GitHub or Google) instead of the admin account, and use the HA install manifest (install.yaml has a -ha variant) when ArgoCD itself is critical. The initial admin secret is a bootstrap path, not a credential management strategy.

Basic Application

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/my-app-deploy
    targetRevision: main
    path: manifests
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

The pieces that matter: source points at the repo+path+revision that holds desired state, destination names the cluster+namespace to deploy into, and syncPolicy.automated is where the GitOps contract lives — prune: true deletes resources that disappear from Git, selfHeal: true reverts out-of-band cluster edits, and syncOptions tweaks edge cases like auto-creating the destination namespace. For the production view of this workflow (SOPS, progressive delivery, rollback), see the GitOps production guide.

ApplicationSet (Multi-Environment)

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-app-multi-env
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - env: dev
            cluster: https://dev-cluster:6443
          - env: staging
            cluster: https://staging-cluster:6443
          - env: prod
            cluster: https://prod-cluster:6443
  template:
    metadata:
      name: "my-app-{{env}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/example/my-app-deploy
        targetRevision: main
        path: "manifests/{{env}}"
      destination:
        server: "{{cluster}}"
        namespace: my-app
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

The list generator is the explicit option — you enumerate dev/staging/prod and the template stamps out one Application per element. Generators are the real power here:

  • list — fixed set of envs/clusters (what you saw above)
  • git — discover Applications from directories or files in a repo
  • cluster — one Application per registered ArgoCD cluster
  • pullRequest — preview environments: an Application per open PR
  • matrix — cartesian product of two generators (env × region)

For production the pullRequest generator is the big win — every PR gets a preview namespace with the PR’s manifests deployed, destroyed on merge.

Git Generator (Auto-discover repos)

The git generator turns directory structure into Applications — a folder per service or env in the deploy repo, and every new directory becomes a new Application on the next reconcile. Adding a service means adding a folder, nothing else. directories walks folders; files reads a manifest per file (useful for per-team config repos).

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: auto-discover
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/example/org-deployments
        directories:
          - path: "*/"
  template:
    metadata:
      name: "{{path.basename}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/example/org-deployments
        targetRevision: main
        path: "{{path}}"
      destination:
        server: https://kubernetes.default.svc
        namespace: "{{path.basename}}"
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

Helm Integration

ArgoCD renders Helm charts natively — no Tiller, no Helm CLI in the cluster. valueFiles layer base→environment overrides in order; parameters are individual key overrides that win over both. Keep environment-specific values in the deploy repo (not the chart’s defaults) so the Application stays the only knob you turn per env.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-helm
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/my-app-deploy
    targetRevision: main
    path: charts/my-app
    helm:
      valueFiles:
        - values.yaml
        - values-prod.yaml
      parameters:
        - name: image.tag
          value: "v1.2.3"
        - name: replicaCount
          value: "3"
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Kustomize Integration

The path points at an overlay — base/ holds the shared manifests, overlays/dev and overlays/prod patch replicas, resources, and image tags. kustomize.images in the Application is a last-minute override, mostly for CI updating the tag. Base stays untouched; overlays own the env-specific deltas.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-kustomize
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/my-app-deploy
    targetRevision: main
    path: overlays/production
    kustomize:
      images:
        - my-app:v1.2.3
      commonLabels:
        env: production
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Sync Strategies

The sync policy decides when desired state becomes live state. The rule of thumb: automated with selfHeal for dev/staging, manual or sync-windowed for production — one bad manifest shouldn’t reach prod unattended.

Automated sync

syncPolicy:
  automated:
    prune: true       # Delete resources removed from Git
    selfHeal: true    # Revert manual changes

Manual sync with hooks

syncPolicy:
  syncOptions:
    - CreateNamespace=true
    - PrunePropagationPolicy=foreground
# Manual sync via CLI: argocd app sync my-app

Sync waves (ordered deployment)

# In your manifests, add annotations:
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "0"  # Runs first
---
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "1"  # Runs second
---
metadata:
  annotations:
    argocd.argoproj.io/sync-wave: "2"  # Runs third

Waves run in ascending order and the sync waits for each wave to report Healthy before starting the next — that’s what lets you land CRDs before the custom resources that need them, or the ConfigMap before the deployment that mounts it. Negative waves run before 0 (use them for namespaces and CRDs).

Sync windows

Block deploys outside business hours without touching the Application:

# In AppProject spec
syncWindows:
  - kind: deny
    schedule: '0 0 * * SAT,SUN'   # no weekend deploys
    duration: 24h
    applications: ['*']
  - kind: allow
    schedule: '0 9-17 * * MON-FRI'
    duration: 8h
    applications: ['*']

Pre/Post sync hooks

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: migration
          image: my-app/migrate:v1.2.3
          command: ["./migrate", "up"]
      restartPolicy: Never
  backoffLimit: 3

Hooks run at lifecycle points: PreSync before the main sync (migrations, schema changes), PostSync after resources are healthy (smoke tests), SyncFail on failure (alerts, cleanup), Skip to exclude a resource from sync entirely. hook-delete-policy controls when the hook resource gets cleaned up — HookSucceeded for fire-and-forget jobs.

RBAC

ArgoCD RBAC is Casbin policy in a ConfigMap — p rules grant subject, resource, action, object, effect, g maps users/groups to roles. Pair it with AppProject for real multi-tenancy: the project constrains which repos, clusters, and namespaces Applications in it may touch, and the RBAC decides who can do what inside that fence.

# argocd-rbac-cm
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.default: role:readonly
  policy.csv: |
    p, role:dev-team, applications, sync, dev/*, allow
    p, role:dev-team, applications, get, dev/*, allow
    p, role:dev-team, applications, action/override, dev/*, deny
    p, role:ops-team, applications, *, */*, allow
    g, dev-team, role:dev-team
    g, ops-team, role:ops-team
# AppProject — the fence around a team's apps
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: dev
  namespace: argocd
spec:
  sourceRepos: ['https://github.com/example/*']   # only these repos
  destinations:
    - server: '*'                                # any cluster
      namespace: 'dev-*'                         # only dev-* namespaces
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace                            # may create namespaces only

Multi-Cluster Management

# Register a cluster with ArgoCD
argocd cluster add prod-cluster --label environment=production

# List registered clusters
argocd cluster list
# Deploy to a specific cluster
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-prod
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/example/my-app-deploy
    targetRevision: main
    path: overlays/production
  destination:
    server: https://prod-cluster:6443  # or name: prod-cluster
    namespace: my-app

Registered clusters live as secrets labeled argocd.argoproj.io/secret-type: cluster in the argocd namespace — argocd cluster add just writes that secret. Combined with the ApplicationSet cluster generator, adding a new cluster = adding one secret, and every Application in the set deploys there automatically.

ArgoCD CLI

The CLI mirrors the UI — anything you can click, argocd app <verb> can do in scripts and pipelines.

# Login
argocd login localhost:8080 --username admin --password <password>

# Application management
argocd app create my-app \
  --repo https://github.com/example/my-app-deploy \
  --path manifests \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace my-app

argocd app sync my-app
argocd app get my-app
argocd app history my-app
argocd app rollback my-app <version>
argocd app delete my-app

# Diff between Git and cluster
argocd app diff my-app

# Utilities that save you in incidents
argocd app wait my-app --health --timeout 120   # block until Healthy in CI
argocd app sync my-app --dry-run                # preview the apply
argocd admin settings rbac can "get, applications" --policy-file argocd-rbac-cm  # test RBAC locally

argocd app diff before merge and argocd app sync --dry-run in CI are the two commands that prevent most GitOps incidents — the diff shows exactly what would change in the cluster for a given manifest.

Notifications

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  service.slack: |
    token: $slack-token
  trigger.on-deployed: |
    - when: app.status.operationState.phase in ['Succeeded']
      send: [app-deployed]
  template.app-deployed: |
    message: |
      {{.app.metadata.name}} deployed to {{.app.status.sync.status}}

Notifications run on the notifications-controller: service.* defines channels (slack, email, webhook, pagerduty), trigger.* the conditions (sync-succeeded, sync-failed, health-degraded, created, deleted), template.* the payload with Go templating over the Application object. Subscribe per-Application or per-ApplicationSet via the notifications.argoproj.io/subscribe.on-deployed.slack: my-channel annotation — no per-app config needed.

Repository Layout

Two layouts cover most teams. App-of-apps: one repo with an Application per environment/service, and a root Application that points at the folder containing them — one bootstrap deploys the whole tree:

deploy-repo/
├── apps/                    # Application manifests (the "app of apps")
│   ├── dev.yaml             # Application → overlays/dev
│   ├── staging.yaml
│   └── prod.yaml
├── base/                    # Kustomize base or plain manifests
└── overlays/
    ├── dev/                 # dev patches (1 replica, small limits)
    ├── staging/
    └── prod/                # prod patches (3 replicas, full limits)

Separate deploy repo vs same repo: keeping manifests in the app repo couples deploy frequency to code merges (every commit triggers a reconcile). A dedicated deploy repo decouples them — CI builds the image, updates the tag in the deploy repo, and ArgoCD picks it up. That separation is what makes multi-env promotion a git operation instead of a redeploy.

Troubleshooting

  • App stuck in SyncWait: usually a hook that never completes (a Job that doesn’t reach Succeeded) or a resource whose health ArgoCD can’t assess — check argocd app get my-app for the hanging resource and its events.
  • OutOfSync that won’t heal: something outside ArgoCD’s tracking (manual kubectl, a webhook-mutated field, an admission controller injecting sidecars) — diff with argocd app diff my-app; if the delta is a controller-managed field, add it to ignoreDifferences in the Application.
  • CRD-dependent resources fail: the CRD and its CRs land in the same sync but the API isn’t registered yet — use sync waves (CRD in wave -1 or 0, CRs later) so the API exists before it’s used.
  • Refresh vs hard refresh: argocd app get my-app --refresh re-polls the repo; --hard-refresh clears the manifests cache too — use it when “nothing changed” but you know it did.
  • Sync works but resources get recreated: prune: true deletes orphaned resources every sync — check argocd app resources my-app for what’s being pruned and add tracking (app.kubernetes.io/instance label) where it belongs.

Production Checklist

Before calling an ArgoCD setup “production ready”:

  • HA install — use the install.yaml HA variant (3 replicas of each component, anti-affinity across nodes) so a node failure doesn’t take your delivery pipeline down
  • SSO only — disable the admin account (argocd-cm admin.enabled: "false"), route everything through Dex/OIDC; local accounts are for break-glass only
  • Projects per team — one AppProject per team or env, with sourceRepos, destinations, and clusterResourceWhitelist constrained; never let dev apps reach prod namespaces
  • Separate deploy repo — manifests live in their own repo; CI updates tags there, never in app code
  • Sync windows for prod — deny windows outside business hours; allow windows when humans are around to watch
  • Alerts on drift and failure — notifications on sync-failed, health-degraded, and OutOfSync that persists past a few minutes
  • Backups of ArgoCD state — argocd-util export regularly; the Applications and projects are state too
  • Monitored controller — ArgoCD is critical infrastructure: alert on its own health, memory, and git fetch errors, not just on the apps it deploys
  • Secrets operator — Sealed Secrets, SOPS, or External Secrets; plain secrets in Git are a leak waiting to happen

Best Practices

  • For a deeper guide, see Complete Guide to GitOps in Production.

  • Store manifests separately from app code — separate deploy repo or directory

  • Use Kustomize overlays — base + per-environment overlays

  • Enable selfHeal — revert manual kubectl changes automatically

  • Use sync waves — ensure CRDs are applied before resources that use them

  • Use AppProject for isolation — restrict which repos, clusters, and namespaces each team can access

  • Pin ArgoCD version — don’t use latest in production

  • Use SSO for ArgoCD — integrate with GitHub, Google, or OIDC

  • Monitor ArgoCD itself — it’s critical infrastructure

  • Use ApplicationSets for scale — avoid creating individual Applications for each microservice

  • Enable notifications — alert on sync failures and drift detection

Common Mistakes

  • Storing manifests in the app repo — coupling deploy frequency to app release frequency
  • Not using selfHeal — manual changes persist and cause drift
  • Giving all teams admin access — use RBAC with least privilege
  • Not using sync waves — CRDs and operators fail if applied out of order
  • Not testing sync before merging — use ArgoCD diff or argocd app sync --dry-run
  • Using automated sync in production without canary — consider manual sync for prod
  • Not monitoring drift — enable notifications for out-of-sync status
  • Forgetting to prune — old resources persist if prune: false

See Also

Frequently Asked Questions

How is GitOps different from CI/CD?

CI builds and tests code. GitOps handles CD — deployment to environments. In GitOps, the deployment is triggered by Git changes, not by CI pushing to a cluster. CI builds images and updates manifests in Git; ArgoCD picks up the manifest change and deploys.

Should I use automated sync in production?

It depends. Automated sync with selfHeal is great for dev and staging. For production, consider manual sync with approval gates, or automated sync with progressive delivery (Argo Rollouts) for canary/blue-green deployments.

How do I handle secrets in GitOps?

Don't store plain secrets in Git. Use Sealed Secrets, SOPS, or External Secrets Operator. These encrypt secrets at rest in Git and decrypt them in the cluster. ArgoCD syncs the encrypted version; the operator handles decryption.

Should I use ApplicationSet or individual Applications?

ApplicationSet once you've got more than a couple of environments or clusters — one template stamps out N Applications from a generator, so adding prod-eu or a new team is a line in the generator, not a new YAML file. Individual Applications only make sense for one-off cases.

How do I roll back a bad deploy?

argocd app rollback my-app <version> — the app history records every sync, so rollback is a new sync to an old state (still GitOps: it's recorded and reversible). git revert works too and is the better long-term answer since it keeps Git honest.

Can I deploy without a Git commit for quick fixes?

You can — argocd app sync my-app --local manifests/ or an ad-hoc kubectl apply — but selfHeal will revert it on the next reconcile, which is exactly the point. For real emergencies: sync to a hotfix branch, or pause auto-sync, patch, and commit the fix properly. The cluster isn't the source of truth; treat out-of-band changes as temporary.