Tenant Management

Manage business tenants at organization and project levels with per-environment service deployments.

Overview

GitOpsHQ supports multi-tenant deployments where the same application is deployed for multiple business customers (tenants) with different configurations per environment. This is the core capability that separates GitOpsHQ from simple GitOps tools — it models the reality of SaaS platforms that serve many customers from a shared infrastructure.

Tenant management operates at two levels:

Organization level — Central tenant registry shared across all projects
Project level — Per-project tenant configurations with environment-specific service deployments

Two-Level Tenant Model

Org Tenants (Organization-Wide)

Org tenants are the central registry of all business tenants in your organization. They represent your customers, regions, or deployment targets at a conceptual level — independent of any specific project or deployment.

Field	Description
Name	Human-readable name (e.g., "Acme Corp", "EU Region")
Slug	URL-safe identifier (e.g., `acme-corp`, `eu-region`), immutable after creation
Description	Optional notes about the tenant
Status	`active`, `suspended`, or `decommissioned`

Org tenants are managed at the organization level and can be linked to multiple projects.

Project Tenants

When an org tenant is linked to a project, it becomes a project tenant. A project tenant represents the deployment configuration for that specific business tenant within the project's scope.

Each project tenant gets:

Per-environment service deployments with custom Helm values
Per-environment Kustomize overlays for Kustomize bindings
Per-environment manifest overlays for manifest bindings
Drift tracking per tenant-environment combination

Linking an org tenant to a project does not automatically create service deployments. You must explicitly assign workloads to tenant-environment pairs (the "scaffold").

Tenant-Environment-Service Hierarchy

The full hierarchy from organization to individual service deployment:

Loading diagram…

Each service deployment (leaf node) has its own:

Helm values document
Image tag configuration
Deployment status (synced, progressing, degraded)
Drift indicator

API Routes

Route	Method	Purpose
`/api/v2/org/tenants`	`GET`	List all org tenants
`/api/v2/org/tenants`	`POST`	Create a new org tenant
`/api/v2/org/tenants/{slug}`	`GET`	Get a tenant by slug
`/api/v2/org/tenants/{slug}`	`PATCH`	Update a tenant
`/api/v2/org/tenants/{slug}/suspend`	`POST`	Suspend a tenant
`/api/v2/org/tenants/{slug}/activate`	`POST`	Reactivate a suspended tenant

Managing Org Tenants

UI Route: /tenants

Navigate to Tenants

From the main navigation or dashboard, click Tenants to open the organization tenant registry.

Create a Tenant

Click Create Tenant. Provide:

Name: Human-readable display name
Slug: URL-safe identifier (auto-generated from name, editable before save)

The slug becomes immutable after creation because it is used in file paths within hosted Git repositories.

View Tenant Details

Click a tenant row to see its detail page. The detail page shows:

Tenant metadata (name, slug, status)
Linked Projects: All projects this tenant is associated with
Quick links to navigate to each project's tenant configuration

Edit or Delete

Edit the tenant name or description at any time. Deleting an org tenant requires unlinking it from all projects first.

Deleting an org tenant is a destructive operation. All associated project tenants, service deployments, overlays, and delivery artifacts will be removed.

Managing Project Tenants

UI Route: /projects/:slug → Tenants tab

Linking Org Tenants to a Project

Open the Project

Navigate to the project and select the Tenants tab. You will see a list of currently linked tenants.

Link a Tenant

Click Link Tenant. A dialog shows all org tenants that are not yet linked to this project. Select one or more tenants and confirm.

Configure the Scaffold

After linking, navigate to the project's Scaffold view to assign workloads to the newly linked tenant across environments.

Unlinking Tenants

Unlinking a tenant from a project removes all per-environment service deployments, overlays, and generated delivery artifacts for that tenant within the project. This action requires confirmation.

Tenant Environment View

UI Route: /projects/:slug/tenants/:tenantId

The tenant detail page within a project provides a comprehensive view of that tenant's deployments across all environments.

Environment Selector

A dropdown or tab bar at the top lets you switch between environments (e.g., dev, staging, production). The view updates to show service deployments for the selected environment.

Service Deployments Table

For each environment, the table shows all assigned workloads:

Column	Description
Service	Workload name (e.g., `api`, `worker`, `frontend`)
Chart	Helm chart name and version
Image	Current image tag
Sync Status	Current sync state from the cluster agent
Drift	Whether drift has been detected
Last Deployed	Timestamp of the most recent successful deployment
Actions	Links to values editor, diff viewer, sync command

Status Indicators

Status	Visual	Meaning
Synced	Green	Cluster state matches desired state
Progressing	Blue (animated)	Deployment in progress
Degraded	Yellow	Partial failure (some pods unhealthy)
Failed	Red	Sync failed or rollback needed
Unknown	Gray	Agent offline, status unavailable

Adding and Removing Services

Add Service: Click "Add Service" to assign an additional workload to this tenant-environment pair. Select from the project's defined workloads.
Remove Service: Remove a workload assignment. This deletes the service deployment's values and stops delivery for that service-tenant-environment combination.

Per-Service Values Editing

UI Route: /projects/:slug/tenants/:tenantId/env/:envId/services/:serviceId/values

The values editor provides a full-featured editing experience for Helm values per service deployment.

Editor Layout

The left pane contains a Monaco editor (the same editor used in VS Code) pre-loaded with the current Helm values for this service deployment. Features include:

YAML syntax highlighting and validation
Auto-completion based on the chart's values.schema.json (if available)
Inline error markers for invalid YAML

The right pane shows contextual reference information:

Chart Defaults: The chart's default values.yaml
Workload Defaults: Project-level default values for this workload
Resolved Values: The final merged values after all layers (chart defaults → workload defaults → environment → tenant-environment)
Chart Schema: If the chart provides a JSON schema, it is rendered as a navigable reference

Save and Commit

When you save changes, GitOpsHQ:

Validates the YAML syntax and schema (if available)
Computes a diff against the current values
Creates a Git commit in the hosted repository with a descriptive message
Triggers the delivery generator to produce updated manifests

Changes are not applied to the cluster immediately — they flow through the normal delivery pipeline (and release workflow if configured).

Kustomize and Manifest Overlays

For projects that use Kustomize bindings or manifest bindings, each tenant-environment pair can have its own overlay.

Kustomize Overlays

UI Route: /projects/:slug/tenants/:tenantId/env/:envId/kustomize/:bindingId

Each Kustomize binding linked to a tenant-environment pair can have an overlay directory. The overlay contains:

kustomization.yaml with patches and transformations specific to this tenant-environment
Patch files (strategic merge patches, JSON patches)
Additional resources

The delivery generator merges the Kustomize base with the overlay using standard Kustomize layering.

Manifest Overlays

UI Route: /projects/:slug/tenants/:tenantId/env/:envId/manifests/:bindingId

Manifest overlays allow per-tenant-environment modifications to raw manifest bundles. Overlays can:

Add additional manifests
Patch existing manifests (via strategic merge)
Override specific fields

Drift and Sync Status

Each tenant-environment combination surfaces a drift indicator derived from the cluster agent's reporting.

Loading diagram…

Drift Resolution

When drift is detected for a tenant-environment:

A yellow or red indicator appears on the service deployment row
Clicking the indicator opens a diff view showing desired vs. actual state
You can trigger a Sync command to reconcile
Or update the desired state if the drift was intentional

Practice	Recommendation
Central governance	Define all tenants at the org level first, then link to projects. Avoid creating tenants only at the project level.
Naming conventions	Use consistent slug formats (e.g., lowercase, hyphen-separated). Slugs are immutable.
Tenant count	Keep below 50 tenants per project for optimal delivery generation performance. For larger deployments, consider splitting into multiple projects.
Environment progression	Always start new tenants in `dev` and promote through environments systematically.
Values inheritance	Use HQ Variables for values shared across tenants. Use per-service values only for tenant-specific overrides.
Overlay management	Keep overlays minimal. If many tenants share the same overlay, consider modifying the base instead.

Core Architecture — Understand the object model hierarchy
Glossary — Definitions of tenant-related terms
Drift Detection — Detailed drift monitoring and resolution
Environment Compare — Compare tenant configurations across environments

On this page