Git as the source of truth

Planned design. TractorStack is in development. This page describes how it is designed to work; nothing here is available to install yet. See the roadmap for the status of each part.

Planned Committed, but not built yet. Everything below describes the planned design.

GitOps for on-premise infrastructure and Kubernetes comes down to one habit: the Git repository is the description of what should be running, and tools make reality match it. In TractorStack, each environment has its own repository in your self-hosted GitLab. If something is not in that repository, it is not supposed to exist; if it is in the repository, a reviewed change put it there.

What the repository describes

The planned layout keeps every layer in one place:

# planned example: one environment repository
tofu/        VMs, disks and networks on Proxmox VE
ansible/     OS hardening, data services, Kubernetes install
compose/     application stacks for stages 1 and 2
k8s/         Helm charts and Argo CD applications, stages 3 and 4
runbooks/    written procedures for people

Versions are pinned throughout: image tags, chart versions, OpenTofu providers and Ansible collections. A pinned version in Git is something you can review, compare and roll back; :latest is not.

GitOps on-premise: two delivery paths

Different parts of the stack need different delivery methods, so the design uses two.

VMs, OS and configuration: through pipelines

Virtual machines, networks, OS settings and data services change through the GitLab pipeline. A merge request triggers a plan, the plan is reviewed and approved, and the site runner applies it with OpenTofu and Ansible. This is a push model: nothing changes until an approved pipeline runs. It suits infrastructure, where an unexpected automatic change, such as resizing a database disk, can be costly.

Kubernetes applications: Argo CD, from stage 3

From stage 3, applications run on a self-managed Kubernetes cluster that Ansible installs and upgrades. Argo CD runs inside the cluster, watches the k8s/ folder and keeps the cluster in line with it. This is a pull model: once a merge request is approved and merged, Argo CD applies the change and keeps applying it if someone edits the cluster by hand. Argo CD also shows each application’s sync and health status, which makes it easy to see what is actually deployed.

In stages 1 and 2 there is no cluster, so Compose stacks are deployed by the pipeline. The application definitions are written to the Kubernetes-ready rules so the move to Argo CD changes the delivery method, not the application.

Drift: the gap between Git and reality

Drift is anything that differs between the repository and what is running: a firewall rule added by hand during an outage, a VM resized in the Proxmox VE console, a config file edited over SSH. The design treats drift as information, not a crime, but it must be found and resolved.

For infrastructure, a scheduled tofu plan and ansible-playbook --check --diff report differences without changing anything. See drift checks.
For Kubernetes, Argo CD marks applications as out of sync and can restore them automatically.

Resolving drift means one of two things: put the manual change into Git through a merge request so it becomes official, or let the next apply remove it. Either way, the repository ends up true again.

Git as the source of truth only works if the repository is the easiest way to make a change. The aim is that a reviewed merge request is faster than logging in and doing it by hand, so people have no reason to go around it.

Last updated 25 October 2026 · Questions or corrections: sales@infratractor.com