Env Compare & Bulk Ops

Overview

As projects grow in complexity — more tenants, more environments, more services — keeping configurations consistent and performing coordinated updates becomes a challenge. GitOpsHQ provides two tools to address this:

1. Environment Compare — Side-by-side comparison of configurations across environments
2. Bulk Image Update — Coordinated image tag changes across multiple tenants and environments

Both features work alongside the webhook system for CI/CD automation.

Environment Compare

UI Route: /projects/:slug/compare

Environment Compare provides a structured, side-by-side view of how configurations differ between any two environments within a project. It is the primary tool for pre-promotion verification — answering the question: "What will change when I promote from staging to production?"

Accessing the Compare View

What is Compared

The compare view analyzes differences across multiple dimensions:

Diff Format

The diff is presented in a familiar unified diff format:

# Tenant: acme-corp / Service: api
# Helm Values Diff

- replicaCount: 2
+ replicaCount: 3

- image:
-   tag: "v1.4.0"
+ image:
+   tag: "v1.3.8"

- resources:
-   limits:
-     memory: "512Mi"
+ resources:
+   limits:
+     memory: "1Gi"

Lines prefixed with - exist in the source environment but not the target. Lines prefixed with + exist in the target but not the source.

Filtering and Navigation

Use Cases

Bulk Image Update

UI Route: /projects/:slug/bulk-update

Bulk Image Update allows you to change container image tags across multiple tenants and environments in a single atomic operation. Instead of editing values for each tenant-environment-service combination individually, you select the scope and apply the update in one action.

Performing a Bulk Update

Changes to commit:
├── tenants/acme-corp/dev/api/values.yaml      image.tag: v1.4.0 → v1.5.0
├── tenants/acme-corp/staging/api/values.yaml  image.tag: v1.3.8 → v1.5.0
├── tenants/beta-inc/dev/api/values.yaml       image.tag: v1.4.0 → v1.5.0
└── tenants/beta-inc/staging/api/values.yaml   image.tag: v1.3.8 → v1.5.0

Total: 4 files changed

Image Update Webhook

Endpoint: POST /api/v1/webhooks/image-update

The image update webhook automates bulk image updates from CI/CD pipelines. When your CI pipeline builds and pushes a new container image, it can notify GitOpsHQ to update matching service deployments automatically.

Webhook Configuration

Configure the webhook in Project Settings → Webhooks → Image Update:

Request Format

{
  "image": "ghcr.io/myorg/api",
  "tag": "v1.5.0",
  "digest": "sha256:abc123...",
  "project": "my-project",
  "workload": "api",
  "environments": ["dev", "staging"],
  "tenants": ["*"],
  "timestamp": "2026-03-27T10:30:00Z"
}

Authentication

The webhook uses HMAC-SHA256 signature verification:

X-GitOpsHQ-Signature: sha256=<HMAC-SHA256(shared_secret, request_body)>

Replay Protection

GitOpsHQ prevents replay attacks by:

1. Requiring a timestamp field in the payload
2. Rejecting requests older than 5 minutes
3. Storing processed request hashes in a shared store and rejecting duplicates

Response Codes

CI/CD Integration Examples

- name: Notify GitOpsHQ of new image
  run: |
    BODY='{"image":"ghcr.io/myorg/api","tag":"${{ github.sha }}","project":"my-project","workload":"api","environments":["dev"],"tenants":["*"],"timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}'
    SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "${{ secrets.GITOPSHQ_WEBHOOK_SECRET }}" | sed 's/.* //')
    curl -X POST https://app.gitopshq.io/api/v1/webhooks/image-update \
      -H "Content-Type: application/json" \
      -H "X-GitOpsHQ-Signature: sha256=$SIGNATURE" \
      -d "$BODY"

notify_gitopshq:
  stage: deploy
  script:
    - BODY='{"image":"registry.gitlab.com/myorg/api","tag":"'"$CI_COMMIT_SHORT_SHA"'","project":"my-project","workload":"api","environments":["dev"],"tenants":["*"],"timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}'
    - SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$GITOPSHQ_WEBHOOK_SECRET" | sed 's/.* //')
    - 'curl -X POST https://app.gitopshq.io/api/v1/webhooks/image-update -H "Content-Type: application/json" -H "X-GitOpsHQ-Signature: sha256=$SIGNATURE" -d "$BODY"'

stage('Notify GitOpsHQ') {
    steps {
        script {
            def body = """{"image":"docker.io/myorg/api","tag":"${env.BUILD_TAG}","project":"my-project","workload":"api","environments":["dev"],"tenants":["*"],"timestamp":"${new Date().format("yyyy-MM-dd'T'HH:mm:ss'Z'", TimeZone.getTimeZone('UTC'))}"}"""
            def secret = credentials('gitopshq-webhook-secret')
            def signature = sh(script: "echo -n '${body}' | openssl dgst -sha256 -hmac '${secret}' | sed 's/.* //'", returnStdout: true).trim()
            httpRequest(
                url: 'https://app.gitopshq.io/api/v1/webhooks/image-update',
                httpMode: 'POST',
                contentType: 'APPLICATION_JSON',
                customHeaders: [[name: 'X-GitOpsHQ-Signature', value: "sha256=${signature}"]],
                requestBody: body
            )
        }
    }
}

ArgoCD Webhook

Endpoint: POST /api/v1/webhooks/argocd

The ArgoCD webhook receives sync status events from ArgoCD notification triggers. This provides a secondary channel for status updates alongside the agent's gRPC reporting.

Configuration

1. In ArgoCD, configure a notification trigger that sends HTTP webhooks on sync events
2. Point the webhook URL to your GitOpsHQ instance's ArgoCD webhook endpoint
3. Configure the HMAC shared secret in both ArgoCD and GitOpsHQ

Payload Format

{
  "app": {
    "metadata": {
      "name": "my-project-acme-corp-dev-api",
      "namespace": "argocd"
    },
    "status": {
      "sync": {
        "status": "Synced",
        "revision": "abc123def456"
      },
      "health": {
        "status": "Healthy"
      }
    }
  },
  "timestamp": "2026-03-27T10:35:00Z"
}

GitOpsHQ parses the application name to identify the project, tenant, environment, and service, then updates the corresponding deployment status.

Best Practices

Related Pages

• Tenant Management — Manage service deployments per tenant-environment
• Drift Detection — Detect configuration divergence after bulk updates
• API Keys and Automation — Configure API keys for webhook authentication
• Dashboard — Monitor the impact of bulk operations