Skip to main content

GitHub Integration Guide

Last updated on

Configure GitHub repository webhooks to send event notifications to Harness AI SRE for deployments, releases, and security alerts.

Before you begin​

  • Harness webhook endpoint: Create a GitHub webhook in Harness AI SRE using the GitHub webhook template.
  • GitHub permissions: Admin access to the repository or organization.
  • Webhook URL: Copy the webhook URL from your Harness webhook configuration.
  • GitHub webhooks documentation: Go to Webhooks Documentation to understand webhook configuration and event types.
  • Event payloads reference: Go to Webhook Events and Payloads for event-specific payload structures.

Create repository webhook​

  1. Go to your GitHub repository
  2. Click Settings, then click Webhooks
  3. Click Add webhook

Configure webhook​

  • Payload URL: Your Harness webhook URL 
    https://<your-harness-instance>/gateway/ai-sre/api/webhooks/<webhook-id>
  • Content type: application/json
  • Secret: (Optional) Webhook secret for signature verification
  • SSL verification: Enable SSL verification
  • Which events: Select events to trigger webhook

Activate webhook​

Enable the webhook so GitHub begins sending events:

  • Check Active to enable the webhook
  • Click Add webhook

Select events to monitor​

Deployment events​

Monitor deployment activities:

Events:

  • Deployments: Deployment created
  • Deployment statuses: Deployment status changed (pending, success, failure, error)

Use cases:

  • Track deployment failures
  • Alert on production deployments
  • Monitor deployment rollbacks

Release events​

Monitor software releases:

Events:

  • Releases: Release published, created, edited, deleted

Use cases:

  • Notify on new releases
  • Track release cadence
  • Monitor hotfix releases

Pull request events​

Monitor code changes:

Events:

  • Pull requests: Opened, closed, merged, reopened
  • Pull request reviews: Submitted, edited, dismissed
  • Pull request review comments: Created, edited, deleted

Use cases:

  • Track deployment-related PRs
  • Monitor high-impact changes
  • Alert on emergency merges

Security events​

Monitor security findings:

Events:

  • Code scanning alerts: Created, fixed, dismissed, reopened
  • Secret scanning alerts: Created, resolved, reopened
  • Dependabot alerts: Created, dismissed, fixed, reintroduced

Use cases:

  • Alert on critical security vulnerabilities
  • Track secret leaks
  • Monitor dependency vulnerabilities

Configure field mapping in Harness​

In your Harness webhook configuration, map GitHub payload fields to alert properties.

GitHub webhook payload structure​

Payload varies by event type. Common structure:

{
  "action": "created",
  "deployment_status": {
    "id": 123,
    "state": "failure",
    "description": "Deployment failed",
    "environment": "production",
    "target_url": "https://example.com/deployment/123",
    "created_at": "2025-07-01T10:30:00Z",
    "updated_at": "2025-07-01T10:35:00Z"
  },
  "deployment": {
    "id": 456,
    "sha": "abc123def456",
    "ref": "main",
    "task": "deploy",
    "payload": {},
    "environment": "production",
    "description": "Deploy to production",
    "creator": {
      "login": "deployer"
    }
  },
  "repository": {
    "name": "my-app",
    "full_name": "myorg/my-app",
    "html_url": "https://github.com/myorg/my-app"
  },
  "sender": {
    "login": "github-actions[bot]"
  }
}

Field mapping by event type​

Basic mapping:

title: "Deployment {{webhook.deployment_status.state}}: {{webhook.repository.full_name}}"
message: |
  Deployment to {{webhook.deployment_status.environment}} {{webhook.deployment_status.state}}
  
  Description: {{webhook.deployment_status.description}}
  SHA: {{webhook.deployment.sha}}
  Ref: {{webhook.deployment.ref}}
  
  View: {{webhook.deployment_status.target_url}}
severity: "{{webhook.deployment_status.state}}"
source: "github"
link: "{{webhook.deployment_status.target_url}}"
tags:
  - "repository:{{webhook.repository.full_name}}"
  - "environment:{{webhook.deployment_status.environment}}"
  - "state:{{webhook.deployment_status.state}}"
  - "ref:{{webhook.deployment.ref}}"

CEL mapping:

title: "Deployment " + webhook.deployment_status.state + ": " + webhook.repository.full_name
message: "Deployment to " + webhook.deployment_status.environment + " " + 
         webhook.deployment_status.state + "\n\n" +
         webhook.deployment_status.description

// Map deployment state to severity
severity: webhook.deployment_status.state == "failure" ? "critical" :
          webhook.deployment_status.state == "error" ? "high" :
          webhook.deployment_status.state == "pending" ? "info" : "info"

source: "github"
link: webhook.deployment_status.target_url

// Filter: only failures and errors
filter: webhook.deployment_status.state in ["failure", "error"]

Test the integration​

Test with webhook delivery​

Redeliver a past webhook payload to test the integration:

  1. Go to Settings, then click Webhooks in your repository
  2. Click your webhook
  3. Select the Recent Deliveries tab
  4. Click Redeliver on any past delivery to test

Trigger real events​

Create a test deployment using GitHub API:

curl -X POST \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/deployments \
  -d '{
    "ref": "main",
    "environment": "staging",
    "description": "Test deployment for Harness integration"
  }'

Verify in Harness​

Confirm the event arrived and mapped correctly:

  1. Navigate to Alerts in Harness AI SRE
  2. Check that the event appears
  3. Verify field mapping is correct

Available GitHub webhook headers​

GitHub sends these headers with all webhooks:

HeaderDescriptionExample
X-GitHub-EventEvent typedeployment_status, release, code_scanning_alert
X-GitHub-DeliveryUnique delivery ID12345678-1234-1234-1234-123456789012
X-Hub-Signature-256HMAC-SHA256 signaturesha256=... (if secret configured)
X-GitHub-Hook-IDWebhook configuration ID123456
X-GitHub-Hook-Installation-Target-IDInstallation/org ID456789
X-GitHub-Hook-Installation-Target-TypeTarget typerepository, organization

Advanced configuration​

Filter by environment​

Only process production deployments:

filter: has(webhook.deployment_status) && 
        webhook.deployment_status.environment == "production" &&
        webhook.deployment_status.state in ["failure", "error"]

Filter by branch​

Only process events from main branch:

filter: (has(webhook.deployment) && webhook.deployment.ref == "refs/heads/main") ||
        (has(webhook.release) && webhook.release.target_commitish == "main")

Route by repository​

Create separate webhooks for different repositories or use routing:

// Tag by repository for routing
tags: [
  "repository:" + webhook.repository.full_name,
  "repo_name:" + webhook.repository.name,
  "event:" + // Extract from X-GitHub-Event header if available
]

Security alert prioritization​

Prioritize critical security alerts:

severity: has(webhook.alert) && webhook.alert.rule.severity == "error" 
  ? "critical" 
  : "high"

// Filter: only security errors
filter: has(webhook.alert) && 
        webhook.alert.rule.severity == "error" && 
        webhook.alert.state == "open"

Troubleshooting​

GitHub webhook is not sending events to Harness AI SRE

Check the webhook Recent Deliveries for errors, verify the webhook URL is publicly accessible, ensure the SSL certificate is valid, and review response codes (200 is success, 4xx/5xx is an error).

GitHub events are not triggering the webhook in Harness AI SRE

Edit the webhook in GitHub, select 'Let me select individual events', enable the required events, then click Update webhook.

GitHub webhook signature verification is failing in Harness AI SRE

Ensure the secret in GitHub matches the Harness configuration, verify Harness is checking the X-Hub-Signature-256 header, and note that GitHub uses HMAC-SHA256, not the legacy HMAC-SHA1.

GitHub webhook payload fields are missing in Harness AI SRE

Check the GitHub webhook documentation for the event-specific payload structure, and use the CEL has() function to check field existence before accessing it.

Example: complete integration​

GitHub webhook configuration​

The following example shows an end-to-end GitHub webhook setup and its field mapping.

  • Payload URL: https://app.harness.io/gateway/ai-sre/api/webhooks/wh_abc123
  • Content type: application/json
  • Secret: your-secure-secret
  • Events:
    • Deployment statuses
    • Releases
    • Code scanning alerts
  • Active: ✓

Harness webhook field mapping example​

# Deployment status events
title: |
  webhook.deployment_status ? 
    "Deployment " + webhook.deployment_status.state + ": " + webhook.repository.full_name :
  webhook.release ?
    "Release " + webhook.release.tag_name + ": " + webhook.repository.full_name :
  webhook.alert ?
    "Security: " + webhook.alert.rule.name + " in " + webhook.repository.full_name :
  "GitHub Event"

message: |
  webhook.deployment_status ?
    "Deployment to " + webhook.deployment_status.environment + " " + webhook.deployment_status.state :
  webhook.release ?
    "Release published: " + webhook.release.name :
  webhook.alert ?
    webhook.alert.rule.description + " (" + webhook.alert.most_recent_instance.location.path + ")" :
  "GitHub event received"

severity: |
  webhook.deployment_status && webhook.deployment_status.state == "failure" ? "critical" :
  webhook.deployment_status && webhook.deployment_status.state == "error" ? "high" :
  webhook.alert && webhook.alert.rule.severity == "error" ? "critical" :
  webhook.alert && webhook.alert.rule.severity == "warning" ? "high" :
  webhook.release ? "info" : "medium"

source: "github"

link: |
  webhook.deployment_status ? webhook.deployment_status.target_url :
  webhook.release ? webhook.release.html_url :
  webhook.alert ? webhook.alert.html_url :
  webhook.repository.html_url

tags:
  - "source:github"
  - "repository:{{webhook.repository.full_name}}"

filter: |
  (webhook.deployment_status && webhook.deployment_status.state in ["failure", "error"]) ||
  (webhook.release && !webhook.release.prerelease && !webhook.release.draft) ||
  (webhook.alert && webhook.alert.rule.severity in ["error", "warning"] && webhook.alert.state == "open")

Next steps​

GitHub official documentation​