Git & Webhooks

Complete guide to the in-app Git repository editor, commit history, blame, batch operations, and webhook management.

Every GitOpsHQ project has a hosted Git repository that serves as the single source of truth for all configuration. This repository stores Helm values, Kustomize overlays, manifest patches, HQ variables, and the generated delivery output. GitOpsHQ provides a full in-app editing experience and an event-driven webhook system for integration with external tools.

Key Concept

The project Git repository is the backbone of GitOps. Every change — whether made through the UI, API, delivery generation, or rollback — results in a Git commit. This provides a complete, auditable history of all configuration changes.

Git File Browser

The file browser is accessible at /projects/:slug/git and provides read-only navigation of the repository contents.

A typical hosted project repository layout:

Feature	Description
File Tree	Hierarchical directory and file listing
File Viewer	Syntax-highlighted content display
Commit History	Chronological list of all commits
File Search	Search for files by name within the repository
Branch Navigation	View the main branch content

In-App Editor

The editor at /projects/:slug/editor provides a full-featured editing experience powered by Monaco (the same engine as VS Code).

Editor Features

Monaco editor with full IntelliSense for YAML and JSON
File tree sidebar with search, create, rename, and delete operations
Multi-file editing with tabs and unsaved change indicators
Drag-and-drop zone: Drop files directly into the editor to add them to the repository
Chart scaffolding: Generate new Helm chart structures from the editor
Commit message input with sensible default messages
Diff view: Review changes before committing

Syntax Highlighting

The editor provides syntax highlighting for all common Kubernetes and DevOps file types:

Language	Extensions
YAML	`.yaml`, `.yml`
JSON	`.json`
Go Templates	`.tpl`, `.gotmpl`
Rego (OPA)	`.rego`
Dockerfile	`Dockerfile`
Shell	`.sh`, `.bash`
Markdown	`.md`
TOML	`.toml`

Batch Commits

Edit multiple files and commit them together as a single atomic change. This is essential for maintaining consistency when related files need to change together.

Example: Updating a Helm chart version across multiple environments requires changing values files in /tenants/acme/staging/values.yaml and /tenants/acme/production/values.yaml simultaneously.

Edit the first file and save it to the staging area (not yet committed).

Navigate to additional files and make changes — each is added to the pending batch.

Review all pending changes in the commit panel.

Write a commit message describing the combined change.

Click Commit Changes to create a single atomic commit.

Editing Workflow

Loading diagram…

Commit History

Every change to the project repository is tracked as a Git commit. The commit history provides:

Field	Description
Commit Hash	Unique SHA identifier
Author	User, service account, or system (for automated changes)
Message	Description of what changed
Timestamp	When the commit was created
Files Changed	List of added, modified, and deleted files

Commit Sources

Commits come from multiple sources, all tracked in the same history:

Source	Description	Example Message
UI Editor	Manual edits via the in-app editor	`Update staging values for api-server`
API	Programmatic changes via the GitOpsHQ API	`[api] Update image tag to v2.1.0`
Delivery Generator	Generated manifests from delivery operations	`[delivery] Generate manifests for acme/production`
Rollback	Configuration restored from a previous state	`[rollback] Revert to release v1.8.2`
Promotion	Changes promoted from one environment to another	`[promotion] Promote staging → production`

Blame View (Pro)

The blame view shows line-by-line attribution for any file in the repository.

Feature	Description
Line Attribution	See who changed each line and when
Commit Navigation	Click any blame entry to view the full commit
Change Context	Understand why a line was changed by reading the commit message
Age Indicators	Visual indicators showing how recently each line was modified

Pro Feature

Blame view is available on the Pro and Enterprise plans. It is invaluable for understanding the history of configuration files and investigating unexpected changes.

Git Authentication

The hosted Git repository supports standard Git smart HTTP protocol for external access.

Clone URL

git clone https://gitopshq.example.com/git/r/{projectSlug}/repo.git

Authentication

Authentication uses HTTP Basic Auth with a project API key:

# Using environment variables
export GIT_USERNAME="api-key"
export GIT_PASSWORD="<your-project-api-key>"

# Clone with inline credentials
git clone https://api-key:<your-project-api-key>@gitopshq.example.com/git/r/my-project/repo.git

Supported Operations

Operation	Command	Description
Clone	`git clone <url>`	Full repository clone
Pull	`git pull`	Fetch and merge latest changes
Push	`git push`	Push local commits to the hosted repo
Fetch	`git fetch`	Download remote changes without merging

Push Permissions

Pushing to the hosted repository requires a project API key with write scope. Commits pushed externally are tracked the same as UI commits and trigger all configured webhooks.

Outbound Webhooks

Outbound webhooks notify external systems when events occur in your project.

Webhook Targets

Channel	Tier	Description
HTTP Endpoint	Free	Send JSON payloads to any HTTP(S) URL
Slack	Pro	Post messages to a Slack channel
Discord	Pro	Post messages to a Discord channel
Microsoft Teams	Pro	Post messages to a Teams channel
Email	Pro	Send email notifications

Event Types

Configure which events trigger webhook deliveries:

Event Category	Events
Release	`release.created`, `release.deployed`, `release.failed`
Promotion	`promotion.requested`, `promotion.approved`, `promotion.executed`
Rollback	`rollback.initiated`, `rollback.completed`
Approval	`approval.requested`, `approval.approved`, `approval.rejected`
Cluster	`cluster.sync.started`, `cluster.sync.completed`, `cluster.drift.detected`
Git	`git.commit.created`, `git.delivery.generated`

Webhook Configuration

Create Webhook Target

Navigate to the project's webhook settings and click Create Webhook. Select the channel type and enter the destination configuration.

Select Events

Choose which event types should trigger this webhook. You can select individual events or entire categories.

Configure Security

For HTTP endpoints, set a webhook secret. GitOpsHQ signs every payload with this secret using HMAC-SHA256, allowing you to verify the payload authenticity.

X-GitOpsHQ-Signature: sha256=<hmac-hex-digest>
X-GitOpsHQ-Event: release.deployed
X-GitOpsHQ-Delivery: <delivery-uuid>

{
  "event": "release.deployed",
  "timestamp": "2026-03-27T10:30:00Z",
  "delivery_id": "d47f3a2b-1234-5678-9abc-def012345678",
  "organization": {
    "id": "org-123",
    "name": "Acme Corp"
  },
  "project": {
    "id": "proj-456",
    "slug": "api-platform",
    "name": "API Platform"
  },
  "payload": {
    "release": {
      "version": "2.1.0",
      "environment": "production",
      "tenant": "acme-corp",
      "deployed_by": "jane.doe@acme.com"
    }
  }
}

Delivery History

The delivery history panel shows all past webhook deliveries with:

Field	Description
Status	HTTP response status code (200, 500, timeout, etc.)
Event	The event that triggered the delivery
Timestamp	When the delivery was attempted
Latency	Response time in milliseconds
Request Body	The full JSON payload sent
Response Body	The response received (truncated for large responses)
Retry Info	Number of retries and retry schedule

Failed deliveries are automatically retried with exponential backoff (1 min, 5 min, 30 min).

Inbound Webhooks

Related Module

Inbound webhooks (image update webhook and ArgoCD webhook) are documented in the API Keys and Automation module. These allow external systems to trigger actions in GitOpsHQ.

Inbound webhook security includes:

Timestamp validation: Reject requests older than 5 minutes
Signature verification: HMAC-SHA256 signature validation
Replay protection: Reject duplicate delivery IDs

Troubleshooting

Error	Meaning	Resolution
`400 path parameter is required`	Missing file path in the API request	Provide a valid file path
`400 q parameter is required`	Missing search query	Provide a search term
`403 webhook limit reached`	Plan-level webhook limit exceeded	Upgrade your plan or remove unused webhooks
`401 missing webhook signature headers`	Inbound webhook missing required auth headers	Verify the sending system includes signature headers
`401 invalid webhook signature`	Signature verification failed	Check the webhook secret matches on both sides
`409 replayed webhook request`	Duplicate inbound webhook delivery ID	This is a security protection; the duplicate request is rejected
`404 file not found`	Requested file does not exist in the repository	Check the file path and branch

Best Practices

Use batch commits for related changes — Keep multi-file updates atomic to avoid partial states
Write descriptive commit messages — Future investigations depend on understanding why changes were made
Review blame for context — Before modifying a file, check blame to understand the history
Configure webhooks for production events — Notify your team immediately when production changes occur
Set webhook secrets — Always use secrets for HTTP webhook targets to verify payload authenticity
Test webhooks before enabling — Use the test delivery feature to verify your endpoint works
Monitor delivery history — Check for failed deliveries regularly and fix integration issues
Use external Git access judiciously — Prefer the in-app editor for most changes; use external Git for bulk migrations