> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/ai-sre/ai-sre-for-administrators/set-up-change-management/deploy-change-investigator.md).

# Set up Deploy Change Investigator

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 <a href="#how-it-works" id="how-it-works"></a>

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](/files/mJluWkIxRd3Frt6Ir0KZ)

**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.

{% hint style="info" %}
**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.
  {% endhint %}

***

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

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 <a href="#set-up-source-control-connector" id="set-up-source-control-connector"></a>

{% hint style="info" %}
**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.
{% endhint %}

**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](/harness-ai/use-harness-platform/connectors/code-repositories/connect-to-code-repo.md) 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](/files/vczQSxX6uW5vAH7PthKq)

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 <a href="#create-a-pr-ingestion-manually" id="create-a-pr-ingestion-manually"></a>

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](/files/uZEUpTGB0K5kmDjPAMod)

***

### Create build webhook integration <a href="#create-build-webhook-integration" id="create-build-webhook-integration"></a>

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 <a href="#create-deploy-webhook-integration" id="create-deploy-webhook-integration"></a>

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 <a href="#configure-build-pipeline-webhooks" id="configure-build-pipeline-webhooks"></a>

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

#### Add the webhook step <a href="#add-the-webhook-step" id="add-the-webhook-step"></a>

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:

```bash
#!/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 <a href="#configure-environment-variables" id="configure-environment-variables"></a>

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`).

{% hint style="warning" %}
**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
  {% endhint %}

#### Build webhook payload reference <a href="#build-webhook-payload-reference" id="build-webhook-payload-reference"></a>

The Build webhook expects this JSON structure:

```json
{
  "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 <a href="#test-build-webhook-and-verify-pr-ingestion" id="test-build-webhook-and-verify-pr-ingestion"></a>

Run your build pipeline and verify two things:

#### Verify build webhook is received <a href="#verify-build-webhook-is-received" id="verify-build-webhook-is-received"></a>

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 <a href="#verify-pr-ingestion-job-was-auto-created" id="verify-pr-ingestion-job-was-auto-created"></a>

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.

{% hint style="info" %}
**SUCCESS CHECKPOINT**

At this point, you should have:

* ✓ Build webhooks flowing (visible in Debug view)
* ✓ PR ingestion job created and running
  {% endhint %}

***

### Configure deploy pipeline webhooks <a href="#configure-deploy-pipeline-webhooks" id="configure-deploy-pipeline-webhooks"></a>

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

#### Add the webhook step <a href="#add-the-webhook-step" id="add-the-webhook-step"></a>

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:

```bash
#!/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 <a href="#customize-the-payload" id="customize-the-payload"></a>

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 <a href="#deploy-webhook-payload-reference" id="deploy-webhook-payload-reference"></a>

The Deploy webhook expects this JSON structure:

```json
{
  "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.

{% hint style="danger" %}
**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.
{% endhint %}

***

### Test deploy webhook <a href="#test-deploy-webhook" id="test-deploy-webhook"></a>

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 <a href="#verification-checklist" id="verification-checklist"></a>

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 <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>PR ingestion job not auto-created after sending build webhooks</summary>

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.

</details>

<details>

<summary>Build webhooks not appearing in Debug view</summary>

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.

</details>

<details>

<summary>Deploy webhooks sending but changes not showing in incidents</summary>

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.

</details>

<details>

<summary>PR ingestion job created but showing no PRs synced</summary>

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.

</details>

***

### Next steps <a href="#next-steps" id="next-steps"></a>

Now that your Deploy Change Investigator is configured:

* Go to [AI Agent RCA](/ai-sre/ai-sre-for-incident-responders/use-ai-agents/rca-change-agent.md) to understand how the AI agent uses change detection during incidents.
* Go to [Incident management workflows](/ai-sre/ai-sre-for-administrators/set-up-incident-management/incidents.md) to manage incidents.
* Go to [Route alerts and integrations](/ai-sre/ai-sre-for-administrators/set-up-alert-management/alert-rules/overview.md) to configure alert routing.