HQ Variables

What Are HQ Variables

HQ Variables are scoped key-value pairs injected into Helm values during delivery generation. They let you manage configuration that varies across repositories, tenants, environments, and services — without duplicating values files or maintaining per-tenant chart forks.

When the delivery generator renders manifests, every {{hq.var.KEY}} placeholder in your values files is resolved against the effective variable map for that specific tenant-environment-service combination. You can also use explicit scope syntax — {{hq.var.repo.KEY}}, {{hq.var.tenant.KEY}}, {{hq.var.env.KEY}}, {{hq.var.svc.KEY}} — to pin resolution to a specific scope.

Variable Scopes

HQ Variables support four hierarchical scopes, from broadest to most specific:

Scope Hierarchy Diagram

Precedence Resolution

When the same variable key exists at multiple scopes, the most specific scope wins. The resolution order is:

Service > Tenant > Environment > Repository

Concrete Example

Consider a variable called REPLICA_COUNT defined at multiple scopes for a repository with two tenants (acme and globex) across staging and production environments:

Resolved values:

The Scope Resolver panel in the UI traces exactly which scope provides the effective value for any given context, so you never have to guess.

Managing Variables

UI Workflow

The Variables panel is accessible at /projects/:slug/variables. It provides a unified interface for all variable operations.

Quick-Insert from Values Editor

When editing Helm values in the workload configuration panel, the HQ Variable quick-insert button lets you reference an existing variable or create a new one inline. The editor inserts the {{hq.var.KEY}} placeholder at the cursor position. For explicit scope pinning, use {{hq.var.repo.KEY}}, {{hq.var.env.KEY}}, {{hq.var.tenant.KEY}}, or {{hq.var.svc.KEY}}.

Bulk Upsert via API

For CI/CD automation, use the bulk upsert endpoint to create or update multiple variables in a single request:

curl -X POST "https://api.gitopshq.com/api/v2/projects/{slug}/variables/bulk-upsert" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "key": "LOG_LEVEL", "value": "debug", "scope": "environment", "scopeId": "env-staging-id" },
      { "key": "FEATURE_NEW_UI", "value": "true", "scope": "environment", "scopeId": "env-staging-id" },
      { "key": "DB_HOST", "value": "db.staging.internal", "scope": "environment", "scopeId": "env-staging-id" }
    ]
  }'

Using Variables in Helm Values

Variables are referenced in values files using the {{hq.var.KEY}} placeholder syntax. The delivery generator resolves these at generation time using scope precedence. For explicit scope pinning, use {{hq.var.repo.KEY}}, {{hq.var.env.KEY}}, {{hq.var.tenant.KEY}}, or {{hq.var.svc.KEY}}.

replicaCount: "{{hq.var.REPLICA_COUNT}}"

image:
  repository: "{{hq.var.IMAGE_REGISTRY}}/my-service"
  tag: "{{hq.var.IMAGE_TAG}}"

resources:
  limits:
    memory: "{{hq.var.MEMORY_LIMIT}}"
    cpu: "{{hq.var.CPU_LIMIT}}"

env:
  - name: DATABASE_URL
    value: "{{hq.var.env.DATABASE_URL}}"
  - name: LOG_LEVEL
    value: "{{hq.var.LOG_LEVEL}}"

Resolution Behavior

• Variables are resolved at delivery generation time, not at Kubernetes apply time.
• The delivery generator builds the effective variable map for the target tenant-environment-service, applies precedence rules, and substitutes all placeholders.
• If a placeholder references a variable key that is not defined at any scope, the delivery generator emits a warning and leaves the placeholder unresolved. The release diff will show the raw placeholder, making it easy to spot.

Variable Impact Preview

Before changing a variable, the impact preview shows the full blast radius of the change:

The preview also flags policy conflicts — if any affected tenant-environment has a freeze or requires approval for variable changes, the preview surfaces this before you save.

Policy Integration

Variable changes participate in the same governance model as all other configuration changes:

• OPA policy evaluation: When FeatureValuesGovernance is enabled, variable updates trigger OPA policy evaluation. Policy violations block the change and surface in the UI.
• Release workflow: Variable changes appear as a change type in releases. If the target environment requires release approval, the variable change goes through the same approval flow.
• Environment freeze: If an environment is frozen, variable changes targeting that environment are blocked until the freeze is lifted or a break-glass session is used.
• Promotion: When promoting from staging to production, variable differences between environments are included in the promotion diff, making it clear what configuration shifts are happening.
• Audit trail: Every variable create, update, and delete is logged with actor, timestamp, old value, and new value.

API Reference

The Variables API supports list/create plus path-based upsert and bulk preview/apply workflows:

Filtering by Scope

# List all environment-scoped variables for staging
GET /api/v2/projects/{slug}/variables?scopeType=environment&scopeId={stagingEnvId}

# List all tenant-scoped variables for a specific tenant
GET /api/v2/projects/{slug}/variables?scopeType=tenant&scopeId={tenantId}

Error Reference

Best Practices