Workloads and Bindings

Workloads and bindings are the core deployment primitives in GitOpsHQ. A workload defines what to deploy; a binding defines where to deploy it. Together, they form the scaffold matrix that maps every deployable unit to its target tenant-environments.

Core Concepts

Workload

A workload (also called a service definition) represents a single deployable unit within a project. Each workload is backed by a Helm chart from the organization's chart registry.

Binding

A binding associates a deployable artifact (workload, Kustomize base, or manifest bundle) with one or more tenant-environment pairs. Bindings carry per-target configuration such as Helm values, Kustomize overlays, or manifest patches.

Scaffold Matrix

The scaffold matrix is the cross-product of workloads (rows) and tenant-environments (columns). Each cell represents a potential deployment slot. The matrix visually shows which workloads are assigned to which tenant-environments.

Three Binding Types

GitOpsHQ supports three binding types, each optimized for a different configuration paradigm.

Workload Bindings (Helm)

Workload bindings are Helm-based. They link a workload (chart reference) to tenant-environments and carry Helm values configuration. Each binding gets its own Helm values file, edited via Monaco editor with chart schema context. Values inheritance allows layered configuration, and chart version tracking with upgrade indicators keeps you informed when newer chart versions are available.

Values inheritance chain:

Each layer can override keys from the previous layer. The delivery generator resolves the full merge at generation time.

Creating a workload binding:

{
  "workloadId": "wl_01H5K...",
  "tenantSlug": "acme",
  "environment": "production",
  "clusterId": "cls_01H5K...",
  "values": {
    "replicaCount": 3,
    "image": {
      "tag": "v2.3.1"
    },
    "resources": {
      "limits": {
        "memory": "512Mi",
        "cpu": "500m"
      }
    }
  }
}

Kustomize Bindings

Kustomize bindings link an org-level Kustomize base to tenant-environments with per-binding overlay editing. Base configuration is defined at the org level and shared across projects. Each binding can add overlays (patches, transformers, generators). Build preview shows the kustomize build output before deploying, and merge preview shows how overlays combine with the base.

Overlay types supported:

Manifest Bindings

Manifest bindings link an org-level manifest bundle to tenant-environments with per-binding raw YAML customization. This is the simplest binding type — raw Kubernetes YAML. Org-level bundles define the base manifests, per-binding overlays allow customization per tenant-environment, and there is no templating engine: what you write is what gets applied. Common use cases include CRDs and cluster-scoped resources, simple one-off deployments, and legacy manifests being migrated into GitOpsHQ.

Creating Workloads

Scaffold Matrix

The scaffold matrix is the central view for managing workload assignments. It appears on the project detail page and provides a grid of workloads x tenant-environments.

Matrix Cell States

Assignment Strategies

Quick Add

From the matrix view, you can click Quick Add on an empty cell to create a new binding with default values. This opens a minimal form with just the essential fields.

Binding Assignments

Each binding links to a specific cluster target and carries sync configuration.

Assignment Properties

Unified Binding View

The project detail page shows all three binding types in a single unified list, filterable by type (Helm, Kustomize, Manifest). Each row shows the binding name, target tenant-environment, type badge, and sync status.

Workload Upgrades

When a chart has a new version in the org registry, workloads referencing that chart show an upgrade indicator in the UI.

Upgrade Workflow

Values Editing

The Values Editor (/projects/:slug/workloads/:id/values) provides a rich editing experience for Helm values.

Editor Features

Values Editing Flow

Every values save creates a Git commit, ensuring full auditability of who changed what and when.

HQ Variable Placeholders

HQ Variables can be referenced in values files using {{hq.var.KEY}} syntax (or pinned forms like {{hq.var.env.KEY}}). The delivery generator resolves these placeholders at generation time using scope precedence (service → tenant → environment → repository).

Overlay Editors

Kustomize Overlay Editor

The Kustomize overlay editor provides specialized tools for building overlays without writing raw YAML:

Both Build Preview (see the kustomize build output) and Merge Preview (see how overlays combine with the base, with additions and deletions highlighted) are available before saving.

Manifest Overlay Editor

A raw YAML editor with syntax highlighting, Kubernetes schema validation, diff view against the base bundle, and final merged output preview.

Binding Lifecycle and Scaffold Generation

From creation to deployment, a binding moves through: Created → Scaffolded → Released → Deployed. Failures at scaffold or deploy stage are recoverable via retry.

When a binding is created or modified, the delivery generator: (1) resolves the chart/base/bundle reference, (2) merges values through the inheritance chain, (3) resolves HQ Variable placeholders, (4) applies overlays, (5) writes rendered manifests to the hosted Git repo, and (6) updates scaffold status.

Rollback Safety and Access Control

Bindings support rollback at multiple levels: values rollback (revert a single binding's values to a prior commit), chart rollback (revert a workload to a prior chart version), release rollback (revert all changes in a release), and selective rollback (cherry-pick specific changes to revert; Enterprise only).

Binding operations are governed by project-level resource grants:

Error Reference

Best Practices

1. Start with the scaffold matrix. Before editing values, get the assignment topology right. The matrix view gives you the full picture of what deploys where.
2. Use values inheritance. Put common configuration at the project level. Use tenant and environment overrides only for values that actually differ.
3. Preview before committing. Use the build preview (Kustomize) or diff view (Helm) to verify your changes before saving.
4. Upgrade workloads in dev first. When a new chart version is available, apply the upgrade in non-production environments before rolling it out to production.
5. Use HQ Variables for secrets and environment-specific config. Variables are resolved at generation time and can be scoped to any level in the hierarchy.
6. Review scaffold failures promptly. A failed scaffold means the binding cannot be deployed. Check the error details and fix the underlying issue (usually a values schema mismatch or missing chart version).