Set up Deploy Change Investigator

Connect builds, deployments, and code changes to understand what changed during incidents.

The Deploy Change Investigator helps you understand what changed when incidents occur by connecting three critical data streams: builds, deployments, and code changes (PRs).

How it works

The investigator connects your CI/CD pipeline data to provide precise answers about "what changed" during incidents:

Deploy Change Investigator architecture diagram showing the flow from Builds, Deploys, and PRs/Code Changes into the Deploy Change Investigator

The connection flow:

1. Build webhook sends: artifact name/version + commit SHA + repository

2. Deploy webhook sends: services deployed + environment + artifact versions

3. PR ingestion fetches: all PRs merged to your main deploy branch

The investigator maps deployments to builds to code changes, giving you precise answers to "what changed?" during incidents.

WHY ALL THREE PIECES MATTER

• Without builds: You cannot map deployments to code changes.

• Without deploys: You cannot correlate incidents to specific releases.

• Without PR ingestion: You cannot show which changes were in the deployment.

---

Prerequisites

Before starting, ensure you have:

• AI SRE module enabled in your Harness account

• Pipeline permissions to add webhook steps to your build and deployment pipelines

• Source control connector (if not using Harness Code): GitHub or Bitbucket credentials configured in your project

---

Set up source control connector

START HERE

Set up your connector first. When you test your build webhook later, AI SRE automatically creates a PR ingestion job for your repository.

Skip this step if: you are using Harness Code (it is already integrated).

For GitHub or Bitbucket:

1. Create a Harness connector for your repository. Go to Connect to a code repo to create one.

2. In the left navigation, click Project Settings (gear icon).

3. Under Project-level resources, select Third Party Integrations (AI SRE).

4. On the Third-Party Integrations for AI SRE page, find the Github or Bitbucket row and select your connector from the dropdown.

Third-Party Integrations for AI SRE page with a connector selected for each source

When you send your first build webhook that includes a source.repository_url, AI SRE automatically creates a PR ingestion job for your repository's main branch.

Create a PR ingestion manually

To create the ingestion without waiting for a build webhook:

1. In the AI SRE left navigation, go to Integrations.

2. Open the PR Ingestions tab.

3. Click + New PR Ingestion.

4. In the Create New PR Ingestion dialog, under Select Git Provider, choose Harness Code, GitHub, or Bitbucket.

5. Enter the Repository URL of the repository to track.

6. Click Create.

Create New PR Ingestion dialog showing Harness Code, GitHub, and Bitbucket as Git provider options with a repository URL field

---

Create build webhook integration

Create an integration that receives build events from your pipeline:

1. In the AI SRE left navigation, go to Integrations.

2. Click + New Integration.

3. Fill in the form:

   • Name: Build (or your preferred name)

   • Type: Build

   • Select Template: Harness Build

4. Click Save.

5. Copy the Endpoint URL. You will need this when you configure your pipeline.

The integration is created with a unique ID (e.g., BUILB1A) and a webhook URL like:

https://app.harness.io/gateway/ir/tp/account/{accountId}/api/v1/mc/webhook/{webhookId}/{token}

---

Create deploy webhook integration

Create a second integration that receives deployment events from your pipeline:

1. While still in AI SRE > Integrations, click + New Integration again.

2. Fill in the form:

   • Name: Deploy (or your preferred name)

   • Type: Deployment

   • Select Template: Harness Deployment

3. Click Save.

4. Copy the Endpoint URL. You will need this when you configure your pipeline.

You should now see both integrations listed in your integrations view.

---

Configure build pipeline webhooks

Add a Shell Script step to your build pipeline that runs after the artifact is published.

Add the webhook step

Add the notification step to your build pipeline:

1. Open your build pipeline

2. Add a new Shell Script step (e.g., "IR Build Notification")

3. Place it after your artifact publishing step

4. Configure the step with the following command:

#!/bin/bash

# The trailing backslashes are line continuations. Bash joins these into a <a href="#the-trailing-backslashes-are-line-continuations-bash-joins-these-into-a" id="the-trailing-backslashes-are-line-continuations-bash-joins-these-into-a"></a>
# single-line JSON string with no embedded newlines. <a href="#single-line-json-string-with-no-embedded-newlines" id="single-line-json-string-with-no-embedded-newlines"></a>
json_payload="{\
\"artifact\": {\"name\": \"${ARTIFACT_REPO}\", \"version\": \"${NEW_VERSION}\"}, \
\"source\": {\
\"commitSha\": \"${COMMIT_SHA}\", \
\"kind\": \"branch\", \
\"value\": \"${BRANCH}\", \
\"repository_url\": \"${MANIFEST_REPO}\"}, \
\"service\": {\"name\": \"${ARTIFACT_REPO}\", \"version\": \"${NEW_VERSION}\"}, \
\"buildId\": \"<+pipeline.executionId>\"}"

curl 'YOUR_BUILD_WEBHOOK_URL_HERE' \
  -s \
  -H 'Content-Type: application/json' \
  -d "$json_payload"

Configure environment variables

Map these variables to your pipeline outputs:

• ARTIFACT_REPO: Maps to <+execution.steps.build_service.output.outputVariables.ARTIFACT_REPO>.

• NEW_VERSION: Maps to <+execution.steps.build_service.output.outputVariables.NEW_VERSION>.

• COMMIT_SHA: Maps to <+codebase.commitSha> or your build step's commit SHA output.

• BRANCH: Maps to <+codebase.branch>.

• MANIFEST_REPO: Your repository URL (for example, https://github.com/yourorg/yourrepo).

• REGISTRY: Your artifact registry (for example, us-west1-docker.pkg.dev).

IMPORTANT NOTES

• Escape all quotes in json_payload

• The assembled json_payload must contain no newlines. The backslash line continuations above keep the source readable while producing a single-line string.

• Replace YOUR_BUILD_WEBHOOK_URL_HERE with the endpoint URL from your Build integration

Build webhook payload reference

The Build webhook expects this JSON structure:

{
  "artifact": {
    "name": "us-west1-docker.pkg.dev/docker/harness-service",
    "version": "1.7.2"
  },
  "source": {
    "commitSha": "9b5866d04b5255f80d7463f7670e3d8a5ff48e34",
    "kind": "branch",
    "value": "release/harness-service-1.7.0",
    "repository_url": "https://github.com/yourorg/harness-service"
  },
  "service": {
    "name": "harness-service",
    "version": "1.7.2"
  },
  "buildId": "abc123"
}

Field mapping:

• artifact.name: Full artifact path (registry + image name)

• artifact.version: Artifact version/tag

• source.commitSha: Git commit SHA that was built

• source.kind: Usually "branch"

• source.value: Branch name

• source.repository_url: Git repository URL

• service.name: Service identifier

• service.version: Same as artifact version

• buildId: Unique build ID (pipeline execution ID)

---

Test build webhook and verify PR ingestion

Run your build pipeline and verify two things:

Verify build webhook is received

Confirm the build integration is receiving events:

1. In the AI SRE left navigation, go to Integrations.

2. Click the More icon (...) on the BUILD integration.

3. Select Debug.

4. You should see a timeline of received webhook events with:

   • Timestamp

   • Payload preview

   • Status (success/failure)

Verify PR ingestion job was auto-created

If you configured your connector, AI SRE should automatically create a PR ingestion job:

1. In the AI SRE left navigation, go to PR Ingestions (tab next to Integrations).

2. You should see an ingestion job with:

   • Repository name

   • Branch being tracked (usually main)

   • Last sync status and timestamp

The job runs automatically and fetches PRs merged to your deploy branch.

SUCCESS CHECKPOINT

At this point, you should have:

• ✓ Build webhooks flowing (visible in Debug view)

• ✓ PR ingestion job created and running

---

Configure deploy pipeline webhooks

Add a Shell Script step to your deployment pipeline that runs after the deployment completes.

Add the webhook step

Add the notification step to your deployment pipeline:

1. Open your deployment pipeline

2. Add a new Shell Script step (e.g., "IR Deploy Notification")

3. Place it after your deployment step

4. Configure the step with the following command:

#!/bin/bash

# The trailing backslashes are line continuations. Bash joins these into a <a href="#the-trailing-backslashes-are-line-continuations-bash-joins-these-into-a" id="the-trailing-backslashes-are-line-continuations-bash-joins-these-into-a"></a>
# single-line JSON string with no embedded newlines. <a href="#single-line-json-string-with-no-embedded-newlines" id="single-line-json-string-with-no-embedded-newlines"></a>
json_payload="{\
\"services\": [\
{\"service\": \"bootstrap\", \"version\": \"1.34.0\"}, \
{\"service\": \"code-api\", \"version\": \"1.42.2\"}], \
\"environments\": [\"qa\"], \
\"changeId\": \"<+pipeline.executionId>\", \
\"status\": \"SUCCESS\", \
\"deployedBy\": \"<+pipeline.triggeredBy.name>\", \
\"deployTimestamp\": \"<+pipeline.startTs>\"}"

curl 'YOUR_DEPLOY_WEBHOOK_URL_HERE' \
  -s \
  -H 'Content-Type: application/json' \
  -d "$json_payload"

Customize the payload

Adjust the payload to match your deployment:

• Replace the services array with your actual services and versions (supports multiple services per deployment)

• Update the environments array with your environment names (e.g., ["prod"], ["staging", "qa"])

• Replace YOUR_DEPLOY_WEBHOOK_URL_HERE with the endpoint URL from your Deploy integration

Using Harness expressions for dynamic values:

• changeId: Maps to <+pipeline.executionId> (unique deployment ID).

• deployedBy: Maps to <+pipeline.triggeredBy.name> (who triggered the deployment).

• deployTimestamp: Maps to <+pipeline.startTs> (when deployment started).

Deploy webhook payload reference

The Deploy webhook expects this JSON structure:

{
  "services": [
    {
      "service": "bootstrap",
      "version": "1.34.0"
    },
    {
      "service": "code-api",
      "version": "1.42.2"
    }
  ],
  "environments": [
    "qa"
  ],
  "changeId": "huEiP2S2TAO-kG-7JHDQJg",
  "status": "SUCCESS",
  "deployedBy": "A. Developer",
  "deployTimestamp": "2025-05-20T21:38:09Z"
}

Field mapping:

• services[]: Array of services deployed (can be one or many).

• services[].service: Service name (must match service.name from the Build webhook).

• services[].version: Artifact version deployed (must match artifact.version from the Build webhook).

• environments[]: Array of environments deployed to.

• changeId: Unique deployment ID.

• status: "SUCCESS" or "FAILURE".

• deployedBy: User who triggered the deployment.

• deployTimestamp: ISO 8601 timestamp of deployment.

CRITICAL MAPPING REQUIREMENT

The services[].service and services[].version must match the corresponding fields from your Build webhooks. This is how the investigator links deployments to builds to commits.

---

Test deploy webhook

After running a deployment, verify the webhook is being received:

1. In the AI SRE left navigation, go to Integrations.

2. Click the More icon (...) on the DEPLOY integration.

3. Select Debug.

4. You should see deployment events with timestamps and payloads.

---

Verification checklist

At this point, you should have:

• ✓ Source control connector configured (if not using Harness Code)

• ✓ Build webhook integration created and receiving events

• ✓ Deploy webhook integration created and receiving events

• ✓ PR ingestion job created and syncing

• ✓ Verified webhook data in Debug views

---

Troubleshooting

PR ingestion job not auto-created after sending build webhooks

Verify: (1) You have a GitHub or Bitbucket connector at Project Settings > Connectors, (2) Build webhook payloads include the source.repository_url field, (3) The repository is reachable. You can also create the ingestion manually under Integrations > PR Ingestions > New PR Ingestion. If all are correct, contact Harness support as a feature flag may need to be enabled.

Build webhooks not appearing in Debug view

Check: (1) The webhook URL is correct and matches the integration endpoint, (2) Your pipeline is reaching the webhook step, (3) The curl command is not failing (add -v flag for verbose output), (4) Network connectivity allows outbound HTTPS to app.harness.io.

Deploy webhooks sending but changes not showing in incidents

Verify that services[].service and services[].version in your deploy webhook exactly match the service.name and artifact.version from your build webhooks. The investigator requires exact string matches to link deployments to builds.

PR ingestion job created but showing no PRs synced

Check: (1) The connector has read permissions on the repository, (2) The branch being tracked matches your actual deploy branch name, (3) PRs have been merged to that branch recently. View the job details for specific error messages.

---

Next steps

Now that your Deploy Change Investigator is configured:

• Go to AI Agent RCA to understand how the AI agent uses change detection during incidents.

• Go to Incident management workflows to manage incidents.

• Go to Route alerts and integrations to configure alert routing.