GitOps

Overview

Use GitOps-first changes for infra and deployment workflows, then validate locally and let Argo CD reconcile. Only apply directly to the cluster when explicitly instructed or in an emergency.

Workflow

1. Locate the source of truth

   • Argo CD apps and overlays: argocd/
   • Kubernetes manifests: kubernetes/
   • IaC: tofu/, ansible/
   • Service-specific instructions: nearest README.md

2. Edit manifests in Git

   • Prefer updating Argo CD apps/overlays instead of raw kubectl applies.
   • Keep environment-specific changes in overlays.

3. Validate locally

   • Argo lint: scripts/argo-lint.sh
   • Kubeconform: scripts/kubeconform.sh argocd
   • Terraform/tofu: bun run tf:plan (apply only when asked)
   • Ansible: bun run ansible

4. Rollout discipline

• Note rollout/impact for changes in argocd/, kubernetes/, tofu/, ansible/.
• For Helm charts with kustomize, use: mise exec helm@3 -- kustomize build --enable-helm <path>.

5. Cluster access (exception-only)

• Use direct kubectl apply only when explicitly asked or in emergencies.
• Always set namespace: kubectl ... -n <ns>.

6. Deploy completion guardrail
   • Only call a deploy "completed" after the Argo CD application is synced and healthy.

Pointers

• Use references/gitops-checklist.md for quick commands and repo-specific notes.