## Why Git fits a Syself Autopilot cluster

A whole workload cluster in Syself Autopilot is declared by a single `Cluster` object (plus a few related manifests). Because the cluster is one declarative object, Git is a natural place to keep it: the file in Git becomes the source of truth for the **entire cluster**, not just for the applications running inside it.

GitOps is **one way** to manage the `Cluster` object, not a requirement. You can always apply and change the object directly with `kubectl`. GitOps adds three things on top:

- **Every change is a pull request**, and merging it is the deploy.
- **Git history is the audit trail**, so you can see who changed what and when.
- **Reconciliation is automatic**, which minimizes drift and manual error.

## Two reconciliation loops

Managing a cluster from Git runs two loops that hand off to each other:

- Syself Autopilot keeps the running cluster matching the `Cluster` object in the management cluster.
- Your GitOps tool keeps that `Cluster` object matching the manifest in Git.

You install the GitOps tool in a workload cluster and add the Syself Autopilot management cluster as an external destination, so the tool can reconcile your `Cluster` declarations. This works for a cluster that already exists too: apply it once by hand, then hand ongoing management to the tool.

## Any GitOps tool works

Because Syself Autopilot is driven through the Kubernetes API, plain Kubernetes YAML works with any GitOps tool. Argo CD and Flux both integrate well. The guides that follow cover both.

## What to put in Git, and what to keep out

Commit the `Cluster` object and its related topology manifests, alongside your application manifests. Keep **secrets** out of Git: reference them through a sealed-secret or an external secret store instead of committing them. Let the **default topology values** Syself Autopilot fills in be reconciled rather than fought over (see [Set up Argo CD](/docs/hetzner/apalla/clusters/gitops/set-up-argo-cd)).

## Fields Syself Autopilot sets for you

Syself Autopilot fills in some parts of the `Cluster` object. The live object therefore always holds more than the manifest you keep in Git. Your GitOps setup has to tolerate that. Otherwise every sync reports drift on a field you never wrote.

`spec.topology.version` is the one to plan for. Syself Autopilot sets the Kubernetes version from the Cluster Stack release that `spec.topology.classRef.name` points at and rewrites it whenever you move the cluster to another release. Leave it out of your manifest and configure your tool to ignore it. The alternative is to keep setting it yourself and change it in the same commit as the class.

GitOps tools can exclude a field from their diff. In Argo CD it is `ignoreDifferences`. See [Ignore the fields Syself Autopilot sets](/docs/hetzner/apalla/clusters/gitops/set-up-argo-cd#ignore-the-fields-syself-autopilot-sets). Flux needs no such rule, because it compares a server-side apply dry run against the live object rather than the live object itself. See [Leave the Kubernetes version out of Git](/docs/hetzner/apalla/clusters/gitops/set-up-flux#leave-the-kubernetes-version-out-of-git).

## Where to go next

- [Set up Argo CD](/docs/hetzner/apalla/clusters/gitops/set-up-argo-cd) to sync your `Cluster` declarations from Git.
- [Set up Flux](/docs/hetzner/apalla/clusters/gitops/set-up-flux) to reconcile your `Cluster` declarations from Git with a Flux `Kustomization`.

If you are new to the platform, you may also want to read the [Concepts overview](/docs/hetzner/apalla/concepts/overview) first.