Core Architecture
Understand how GitOpsHQ works — its architecture, object model, and delivery philosophy.
What is GitOpsHQ
GitOpsHQ is a unified GitOps control plane that manages Kubernetes deployments across organizations, projects, tenants, and environments. It provides a single pane of glass for:
- Helm charts, Kustomize bases, and raw manifest bundles as reusable artifacts
- Release management with approval workflows and promotion pipelines
- Rollback operations — full or selective — to recover from bad deployments
- Governance policies including environment freezes, approval gates, and audit logging
- Multi-tenant delivery — deploy the same application for many business customers with per-tenant configuration
Whether you are managing a handful of microservices or orchestrating hundreds of tenant-specific deployments across multiple clusters, GitOpsHQ gives your platform team a declarative, auditable, and scalable delivery layer on top of Kubernetes.
Architecture Overview
GitOpsHQ follows a hub-and-spoke topology. The hub is a SaaS platform; the spokes are lightweight agents running inside your Kubernetes clusters.
| Component | Technology | Role |
|---|---|---|
| Hub — Backend | Go (net/http, gRPC server) | API server, delivery generator, policy engine, audit log |
| Hub — Frontend | React + TypeScript + Tailwind | Dashboard, resource editors, release management UI |
| Hub — Database | PostgreSQL + SQLite (per-project hosted repos) | Persistent state, org data, audit trail |
| Cluster Agent | Go binary (single pod) | Outbound gRPC connection to hub, inventory reporting, command execution |
| Runtime Adapter | ArgoCD or Flux (your choice) | Applies generated manifests to the cluster |
Cluster agents initiate outbound gRPC connections to the hub. No inbound ports need to be opened on your clusters, making GitOpsHQ firewall-friendly and compatible with private networks.
Object Model Hierarchy
Every resource in GitOpsHQ belongs to an Organization — the top-level isolation boundary. Within an organization, resources are organized into a clear hierarchy.
Organization-Level Resources
| Resource | Description |
|---|---|
| Members | Users with roles: owner, admin, member, viewer. Owners have full control; viewers have read-only access. |
| Teams | Named groups of members. Permissions are granted to teams via resource-scoped grants. |
| Service Accounts | Machine identities for CI/CD automation. Each has scoped tokens with configurable allowed actions. |
| Org Tenants | Central registry of business tenants (e.g., your SaaS customers). Linked to projects for per-tenant delivery. |
| Org Environments | Ordered environment stages (e.g., dev → staging → production). Projects inherit these definitions. |
| Org Charts | Reusable Helm chart registry. Upload chart versions and reference them in project workloads. |
| Org Kustomize Bases | Reusable Kustomize configurations. Applied via bindings at the project level. |
| Org Manifest Bundles | Collections of raw Kubernetes YAML manifests. Applied via bindings at the project level. |
| Clusters | Registered Kubernetes clusters. Each cluster runs an agent and can be targeted by one or more projects. |
Project-Level Resources
| Resource | Description |
|---|---|
| Environments | Project-specific environment configuration, inheriting from org environments. Each has a target cluster. |
| Tenants | Links to org tenants. Each project tenant gets per-environment service deployments with custom Helm values. |
| Workloads | Helm chart-based service definitions. A workload references an org chart and defines default values. |
| Kustomize Bindings | Associates a Kustomize base with specific tenant-environment pairs, with optional overlays. |
| Manifest Bindings | Associates a manifest bundle with specific tenant-environment pairs, with optional overlays. |
| Releases | Versioned change sets. A release collects pending changes and moves through approval → deploy workflow. |
| HQ Variables | Scoped key-value configuration. Variables can be scoped to org, project, environment, tenant, or service level. |
| Hosted Git Repository | An in-app Git repository managed by GitOpsHQ. Stores all generated delivery manifests and user-authored overlays. |
Delivery Philosophy
GitOpsHQ treats Git as the single source of truth for all deployment configuration. Every change — whether made through the UI, API, or webhook — results in a Git commit.
Change is authored
A user updates Helm values in the UI, a CI pipeline sends an image-update webhook, or an operator creates a release via the API.
Git commit is created
GitOpsHQ writes the change to the project's hosted Git repository as a structured commit. The commit message includes the author, scope, and a human-readable description.
Delivery Generator runs
The delivery generator resolves all bindings (workloads × tenants × environments), merges HQ variables, applies overlays, and produces final rendered manifests per tenant-environment-service.
Runtime adapter applies
ArgoCD or Flux detects the new commit in the hosted repo and applies the rendered manifests to the target cluster. Sync status flows back to GitOpsHQ via the agent.
Multi-Tenancy Model
GitOpsHQ supports two distinct layers of multi-tenancy:
Platform Multi-Tenancy (Organization Isolation)
Each organization is a fully isolated tenant of the GitOpsHQ platform. Organizations do not share data, clusters, or configurations.
Business Multi-Tenancy (Tenant Deployments)
Within a project, you can model business tenants — your own customers or deployment targets. The same set of workloads can be deployed for each tenant with different configurations per environment.
| Scenario | How to model it |
|---|---|
| Single-tenant SaaS | One project, one tenant, multiple environments |
| Multi-tenant SaaS | One project, many tenants, each with per-env service configs |
| Platform team managing multiple apps | Multiple projects, shared org tenants across projects |
| Regional deployments | Org tenants as regions, environments as stages within each region |
Agent Architecture
The cluster agent is a single Go binary deployed as a Kubernetes Deployment (one replica). It is the only component that needs to run inside your cluster.
Agent Capabilities
| Capability | Description |
|---|---|
| Inventory | Reports cluster resources, namespaces, and node information |
| ArgoCD Status | Monitors ArgoCD Application sync status and health |
| Resource Inspection | Retrieves specific resource details on demand |
| Log Streaming | Streams pod logs back to the hub for debugging |
| Command Execution | Executes commands (sync, rollback, restart, scale) received from the hub |
| Heartbeat | Sends periodic health signals; hub detects agent disconnection |
Security Model
- Agent authenticates via a cluster token issued at registration time
- All communication is TLS-encrypted over gRPC
- Agent tokens can be rotated without re-deploying the agent
- The agent requires only outbound network access to the hub endpoint
- No cluster admin credentials are stored in the hub
Feature Tiers and Runtime Notes
Roadmap/commercial packaging is modeled as Free / Pro / Enterprise. At runtime, feature enforcement is controlled by feature gates (pkg/features/*) and route wiring (internal/server/routes_protected.go).
| Capability Family | Roadmap Target Tier | Runtime Feature Gate |
|---|---|---|
| Core project/workload/registry flows | Free | Baseline (no extra gate) |
| Promotion pipeline | Pro | FeaturePromotion |
| Advanced rollback flows | Pro + Enterprise variants | FeatureRollback, FeatureSelectiveRollback, FeatureRollbackApproval |
| Teams and resource permissions | Pro | FeatureTeams, FeatureResourcePermissions |
| Notifications (preferences) | Pro | FeatureNotifications |
| Notification policy escalation | Enterprise | FeatureAlertEscalation |
| K8s validation and CRD schema upload | Free + Enterprise extension | FeatureK8sValidation, FeatureCRDSchemas |
| Values governance / policy sets | Pro+ | FeatureValuesGovernance |
| SAML/SCIM and other enterprise roadmap items | Enterprise (roadmap) | feature constants exist; dedicated auth/provisioning routes are not yet exposed |
Current OSS Build Behavior
The default community build reports plan enterprise and enables all feature constants (pkg/features/community.go). Use GET /api/v2/features to inspect the effective plan/features/limits in your deployment instead of assuming static tier tables.
What's Next
- Glossary — Learn the vocabulary used throughout GitOpsHQ
- Dashboard — Explore the real-time command center
- Tenant Management — Understand multi-tenant delivery
- API Keys and Automation — Integrate GitOpsHQ with your CI/CD pipelines
- Reference — Deep technical mapping for roadmap, gates, limits, and API surface