Proxmox‑GitOps implements a self‑contained CI/CD control plane for Proxmox VE that bootstraps from a single repository and manages itself recursively within the LXC containers under management

Repository: https://github.com/stevius10/Proxmox-GitOps

Demo (1min+): https://youtu.be/2oXDgbvFCWY?si=gSSACmVi0mO6v8xx

Architecture

- A local bootstrap (`./local/run.sh`) seeds a Gitea instance and runner, initializes the pipeline, and creates an initial PR. Merging this PR transitions the system into self-management; subsequent commits converge the desired state across Proxmox LXC containers.

- The system uses a self-contained monorepo with reusable container libraries. Ansible handles provisioning against Proxmox, while Cinc (Chef) performs desired-state convergence and cross-layer orchestration where declarative modeling is insufficient.

Concept

- Recursive self-management: the control plane executes within the managed containers to maximize reproducibility and minimize drift.

- Git as current desired state: operations map to standard Git workflows (commit, merge, rollback) in a stateless management model.

- Convention-based extensibility: add a service by copying a container definition from libs, adding a minimal cookbook and `config.env`; the pipeline handles provisioning, configuration, and validation.

- Loose coupling: containers remain independently replaceable and continue to function without manual follow-up.

Environment

- Proxmox VE 8.4–9.0, Debian 13 LXC per default.

- Local bootstrap via Docker; further actions are repository-driven.

Install

- Configure Proxmox credentials in `./local/config.json`. - Run `./local/run.sh` to seed the environment.

- Accept the initial PR in the seeded Gitea instance at `localhost:8080/main/config`.

- Push changes to trigger provisioning, convergence, and validation on Proxmox VE.

Trade-Offs

- The recursive bootstrap increases complexity to preserve rebuild‑from‑repo semantics and deterministic behavior.

- On Proxmox 9, stricter token privileges limit certain operations; automation uses root‑context API access where tokens are insufficient.