# Course VI - GitOps: ArgoCD, the GitHub linkage, and the one thing git never holds

**Series position:** first course of the delivery arc (VI-VIII). The main menu taught the
machine; this arc teaches how software REACHES it.
**Safety gate:** public site, real name - technologies only, zero employer/industry framing.
Claims source from [[argocd-stacks]], [[gitops-iac-rigor]], [[eso-infisical-secrets]]
(generalised to the Azure Key Vault worked example), [[authentik-oidc]] not needed here.

## Title (thesis)
**Nobody deploys anything. The cluster syncs itself.**

## Hook - the uncomfortable default
The mental model everyone arrives with: a person (or a pipeline) with credentials pushes
manifests at the cluster. Deploy = an action someone performs, kubectl apply = the verb.
The inversion: in GitOps nothing is pushed. A repository holds the desired state, an agent
inside the cluster watches it, and the cluster pulls its own future from git. kubectl is
for looking, git is for changing.

## Move 1 - The loop you already know, one level up
Course II taught the reconciliation loop: desired vs actual, fix the difference, repeat.
ArgoCD is the same habit applied to DELIVERY. An Application names a repo + path + revision
(the GitHub linkage: watch this branch of this repository); the controller renders what it
finds there, compares it against the live cluster, and shows the diff. Sync = make actual
match desired. The deploy button is a git commit; the audit log is git log; code review IS
change control.
Say it like you mean it: **kubectl apply is for archaeology, not for change.**

## Move 2 - Pull, not push - the security inversion
The load-bearing detail everyone misses: the cluster PULLS. No CI system, no laptop, no
GitHub Action holds a credential that can touch the cluster. The agent inside the cluster
holds a read-only deploy key to the repo - the trust arrow points OUT. Compromise the build
system and you can propose a change (a commit, which is visible); you cannot reach into
production. Drift works the same way: hand-edit a live object and the controller flags it
OutOfSync - with selfHeal on, it puts it back; with prune on, what leaves git leaves the
cluster. Rollback is `git revert`, which is why commit hygiene is an operational skill.
FIELD NOTE (amber): fighting the reconciler by SSH/kubectl is arm-wrestling a machine that
does not get tired (Course II's note, now with a face). The fix is always upstream, in git.

## Move 3 - The one thing git never holds
Git holds everything - manifests, charts, config, the whole desired state - except secrets.
A secret in git is published, forever, to everyone who ever clones. So the pattern splits
the reference from the value: git carries an ExternalSecret manifest naming a LOGICAL key
("this app needs db-password from the vault"); a vault - Azure Key Vault as the worked
example, any ESO-supported store works - holds the value; an operator inside the cluster
exchanges the reference for the value at runtime and keeps it synced. Rotation happens in
the vault, never as a commit.
Say it like you mean it: **git holds the shape of the secret, the vault holds the secret.**
FIELD NOTE: the day a real credential lands in a commit, it is spent - history rewrites do
not un-publish it. Rotate first, tidy git second.

## Close
Delivery stops being an event and becomes a property: the cluster is always converging on
what the repository says. The question "who deployed this?" becomes "who merged this?" -
and that question always has an answer.

## Legend terms (DOM layer)
Application (repo + path + revision) / desired vs actual / sync / drift / selfHeal /
prune / pull model / deploy key / ExternalSecret / vault reference / rotation

## Scene concept (hero + slices, the v3 mechanism)
Exploded chain, upper-left to lower-right: a faceted crystal SLAB etched with branching
lattice (the repository) -> a compare-loop ENGINE with two counter-rotating ring motifs
(ArgoCD: desired vs actual) -> a stack of thin rendered SHEETS (manifests) -> the cluster
CORE (Course II's command slab, familiar silhouette) -> off-axis, drifting away dimmed: a
small GHOST SHARD (the hand-edit being reverted). Separate armoured VAULT BOX floating
above the chain, apart from everything (the secret store - deliberately not in line).
6 parts, no connectors. Slice plan: collapse packs chain into the engine; vault stays
apart even collapsed (it is never absorbed into the pipeline - the visual argument).

## Page footer - pre-reads + further reading (site convention: every course carries this)
Pre-reads: Course II (the reconciliation loop - this course is that loop one level up);
Kubernetes concepts (https://kubernetes.io/docs/concepts/); git + pull requests
(https://docs.github.com/en/get-started).
Further reading: Argo CD docs (https://argo-cd.readthedocs.io/); Red Hat OpenShift
GitOps (via https://docs.redhat.com/en/documentation/openshift_container_platform);
External Secrets Operator (https://external-secrets.io/); Azure Key Vault
(https://learn.microsoft.com/azure/key-vault/); Helm docs (https://helm.sh/docs/).
