Portefaix docs GitHub

GitOps Principles

GitOps is an operational model for managing infrastructure and application configuration by using Git as the single source of truth. This page explains what GitOps means for Portefaix and why the platform is designed around it.

Reading this page will help you understand the reasoning behind how Portefaix is structured, why all changes flow through Git, and what the reconciliation loop achieves. If you want to perform a specific GitOps task, see the ArgoCD bootstrap how-to instead.

The four OpenGitOps principles

Portefaix follows the OpenGitOps specification, which defines four principles that together describe a complete GitOps system.

1. Declarative

A system managed by GitOps must have its desired state expressed declaratively. Rather than writing scripts that describe how to reach a state, you write manifests that describe what the state should be.

In Portefaix, every component — from Kubernetes workloads to Terraform infrastructure — is expressed as declarative configuration: Kubernetes YAML, Helm values files, and Terraform HCL. Nothing is configured by running imperative commands in production.

2. Versioned and immutable

Desired state is stored in a system that enforces immutability and retains a complete version history. Git is the canonical implementation: every change is a commit, commits are content-addressed, and history is append-only.

This gives Portefaix full auditability. Every change to cluster state has a corresponding Git commit with an author, timestamp, and message. Rolling back is as simple as reverting a commit — the reconciler automatically restores the previous state.

3. Pulled automatically

Software agents automatically pull the desired state declarations from the source. This is the inversion that distinguishes GitOps from traditional push-based CI/CD: nothing pushes configuration into the cluster from outside.

ArgoCD is Portefaix's pull agent. It polls the Git repository (and responds to webhooks for low-latency updates), computes the diff between desired and actual state, and applies changes. Cluster credentials never need to leave the cluster perimeter.

4. Continuously reconciled

Software agents continuously observe actual system state and attempt to apply the desired state. Drift — any divergence between desired and actual state — is detected and corrected automatically.

ArgoCD runs a reconciliation loop every 3 minutes by default, and can also be triggered instantly via webhook. If someone manually applies a resource change with kubectl, ArgoCD will detect the drift and revert it at the next reconciliation cycle. This makes manual configuration changes impossible to maintain accidentally.

Why GitOps for platform engineering?

Platform teams manage infrastructure for other teams. This creates a tension: changes need to be fast (developers are waiting), safe (production is critical), and auditable (compliance requires traceability).

GitOps addresses each of these:

  • Speed via automation: the reconciler applies approved changes within seconds, no manual deployment steps required.
  • Safety via pull requests: all changes go through code review before being applied. The Git history is the deployment log.
  • Auditability by design: every state transition is a commit. Compliance questions ("what was running on 15 March?") are answered with git log.

The role of ArgoCD in Portefaix

ArgoCD is not the only GitOps tool available (FluxCD is a popular alternative), but Portefaix chose ArgoCD because of its rich UI, ApplicationSet controller for multi-cluster management, and its support for Helm and Kustomize natively.

FluxCD was supported in Portefaix v1 but has been deprecated since v2.0.0. Teams migrating from FluxCD to ArgoCD will find the conceptual model is identical — only the tooling differs.

GitOps and infrastructure (Terraform)

Kubernetes GitOps (ArgoCD managing in-cluster resources) is distinct from infrastructure GitOps (Terraform managing cloud resources). Portefaix uses both:

  • Infrastructure layer (portefaix-infrastructure): Terraform manages cloud resources — clusters, networking, IAM. Changes are applied via CI/CD pipelines (GitHub Actions or Spacelift) triggered by merges to the main branch.
  • Kubernetes layer (portefaix-kubernetes): ArgoCD manages everything inside the cluster — Helm releases, Kyverno policies, Custom Resources.

The two layers are intentionally separate. Infrastructure changes are infrequent and require explicit pipeline approval. Kubernetes configuration changes are continuous and managed entirely by ArgoCD.

Further reading