duocthu/docs/adr/0002-argocd-gitops.md

ADR 0002: Use the team's existing ArgoCD instance for deployment (GitOps)

Status

Accepted

Context

Phase 6 of the build roadmap needs a way to actually deploy the Helm chart to Kubernetes across dev/staging/prod. The original scaffold (infra/ci/github-actions/deploy-cd.yml) assumed a push-based CI deploy step (CI runs helm upgrade/kubectl apply directly against the cluster). The team already runs an ArgoCD instance used by other projects.

Decision

Deploy via GitOps through the team's existing ArgoCD instance instead of building a custom push-based CD pipeline. ArgoCD Applications (infra/argocd/applications/{dev,staging,prod}/app.yaml) point at infra/helm/medical-chatbot in this repo; ArgoCD watches the repo and reconciles the cluster to match.

Rationale

• Reuses infrastructure the team already operates and trusts, instead of standing up a parallel deploy mechanism.
• GitOps gives an auditable history of every deploy (it's just git commits changing values files/image tags) and a built-in rollback path (revert the commit).
• Removes the need for CI to hold cluster credentials — CI's job shrinks to "build, test, push image, bump tag," which is a smaller security surface than "CI can directly mutate the production cluster."
• Prod uses a non-automated syncPolicy (manual approval in ArgoCD) while dev/staging auto-sync, matching normal caution around production changes.

Consequences

• CI workflows (infra/ci/github-actions/*.yml) build/test/push images and bump the relevant values-<env>.yaml image tag + push that commit; they do not call kubectl/helm against any cluster directly.
• Actual deploy execution and health/sync status live in the team's ArgoCD UI/CLI, outside this repo — runbooks in docs/runbooks/ should document how to check sync status and roll back once the team's ArgoCD instance details (cluster/server, project, repo URL) are confirmed (see TODOs in infra/argocd/README.md).
• If the team's ArgoCD instance becomes unavailable or this project needs to fully own its own deploy tooling later, the push-based deploy-cd.yml approach remains a documented fallback.