GitOps with ArgoCD
Summary
Keymate supports a GitOps deployment model using ArgoCD as the orchestration layer. In this model, the desired platform state is declared in a Git repository, and ArgoCD continuously reconciles the cluster to match that state. This provides automated deployment ordering, drift detection, rollback capability, and auditability through Git history.
We recommend GitOps with ArgoCD for teams that already use or plan to adopt GitOps practices. It is not a requirement — the Kubernetes Native model with direct Helm installation is equally valid.
Why It Exists
Deploying a multi-component platform like Keymate involves installing dozens of services in the correct dependency order, managing configuration across environments, and keeping production state consistent with what was tested. Manual Helm installations work, but they require discipline to maintain consistency over time.
ArgoCD solves this by treating Git as the single source of truth. Every change to the platform configuration goes through a Git commit, making deployments auditable, repeatable, and reversible.
Where It Fits in Keymate
GitOps with ArgoCD builds on top of the Kubernetes Native model. The same Helm charts are used — ArgoCD orchestrates their installation and lifecycle management rather than replacing Helm.
Kubernetes Native (Helm charts)
└── GitOps with ArgoCD (orchestration layer on top)
This model is one of two installation paths documented in Platform Deployment:
- Helm-Based Installation — direct Helm, no ArgoCD
- GitOps-Based Installation — ArgoCD manages everything
Boundaries
This model covers:
- How ArgoCD orchestrates Keymate platform deployment
- The benefits of declarative, Git-driven delivery
- When to choose this model over direct Helm installation
- How multi-environment promotion works with GitOps
This model does not cover:
- ArgoCD installation and configuration (refer to the ArgoCD documentation)
- Direct Helm installation without ArgoCD (see Kubernetes Native)
- Automated cluster provisioning (see Infrastructure Provisioning)
How It Works
Declarative Deployment
With the GitOps model, you define the complete platform configuration in a Git repository. This includes which components to deploy, their versions, Helm values, and environment-specific overrides. ArgoCD watches this repository and synchronizes the cluster to match the declared state.
Key Capabilities
| Capability | What it provides |
|---|---|
| Automated dependency ordering | ArgoCD deploys components in the correct sequence without manual intervention |
| Drift detection | ArgoCD continuously compares the cluster state against Git and reports any divergence |
| Rollback | Reverting to a previous configuration is a Git revert — ArgoCD applies the change automatically |
| Audit trail | Every deployment change is a Git commit with author, timestamp, and diff |
| Environment promotion | Changes move from dev to staging to production through Git branch or directory-based workflows |
| Self-healing | If someone manually modifies a resource in the cluster, ArgoCD detects the drift and can restore the declared state |
Deployment Flow
- A platform engineer commits a configuration change to the GitOps repository
- ArgoCD detects the change and calculates the difference between Git and the cluster
- ArgoCD applies the changes in the correct dependency order
- ArgoCD deploys, updates, or removes components to match the declared state
- ArgoCD reports the synchronization result (synced, out-of-sync, degraded)
When to Choose This Model
Choose GitOps with ArgoCD when:
- Your team already uses or wants to adopt GitOps practices
- You need audit trails for every deployment change
- You manage multiple environments (dev, staging, production) and want consistent promotion
- You want automated drift detection and self-healing
- You deploy frequently and need repeatable, low-risk delivery
Choose Kubernetes Native (direct Helm) when:
- You prefer direct control over individual Helm releases
- Your team does not use GitOps tooling
- You have a single environment with infrequent changes
- You want the minimal deployment footprint without additional orchestration tools
Diagram
Example Scenario
Scenario
A platform team at Acme Corp manages Keymate across three environments: development, staging, and production. They use ArgoCD for all deployments and promote changes through Git pull requests.
Input
- Actor: Platform Engineer
- Environments: dev, staging, production — each in a separate Kubernetes cluster
- Method: ArgoCD watching a GitOps repository with environment-specific configurations
- Change: Upgrading the authorization engine to a new version
Expected Outcome
- The engineer updates the component version in the dev environment configuration and commits to Git
- ArgoCD deploys the new version to the dev cluster automatically
- After validation, the engineer opens a pull request to promote the change to staging
- The same process repeats for production after staging validation
- Every step is tracked in Git history with full audit trail
Common Misunderstandings
- "ArgoCD is the only way to deploy Keymate." ArgoCD is one option. The Kubernetes Native model with direct Helm works without any GitOps tooling.
- "GitOps means I lose control over deployments." You control exactly what gets deployed through Git commits. ArgoCD applies what you declare — nothing more, nothing less.
- "I need to learn ArgoCD from scratch to use this model." Teams already using ArgoCD can add Keymate as another application set. The deployment configuration follows standard ArgoCD patterns.
ArgoCD manages the lifecycle of deployed resources. Avoid making manual changes to Keymate resources in the cluster — ArgoCD will detect these as drift and may overwrite them during the next sync cycle.
Design Notes
- The GitOps model uses the same Helm charts as the Kubernetes Native model. The difference is in how those charts are managed and orchestrated, not in the charts themselves.
- ArgoCD handles component dependency ordering automatically. You do not need to manually sequence Helm installs.
- Multi-environment management is a natural fit for GitOps. You maintain environment-specific configuration as separate value sets within the same repository.
Start with a single environment (dev) to validate the GitOps workflow before expanding to staging and production. This reduces risk and builds team familiarity with the deployment process.