> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/mechanism.md).

# Mechanism

Understand the change tracking mechanism—how Pharos monitors the audit trail and commits metadata snapshots to GitHub.

Change Tracking operates through a simple but effective pipeline: monitor the Salesforce Setup Audit Trail for changes, retrieve the affected metadata, and commit it to a GitHub repository. This process runs automatically on an hourly cycle.

***

## How It Works

### Step 1: Audit Trail Monitoring

On an hourly basis, Pharos checks your Salesforce org's **Setup Audit Trail** for recent entries. The audit trail records administrative changes—metadata modifications, configuration updates, and structural changes to your org.

{% hint style="info" %}
**Why the Audit Trail?** Rather than continuously scanning all metadata for differences (which would be API-intensive), Pharos uses the audit trail as a lightweight change detection signal. If the audit trail shows changes, Pharos knows exactly what to retrieve.
{% endhint %}

### Step 2: Metadata Retrieval

When changes are detected, Pharos retrieves the current state of the affected metadata components from your org. This includes the full content of the component—not just a notification that something changed.

### Step 3: GitHub Commit

The retrieved metadata is committed to your configured GitHub repository. Each commit includes:

| Element           | Detail                                               |
| ----------------- | ---------------------------------------------------- |
| **Changed files** | The metadata components that were modified           |
| **Timestamp**     | When the change was detected and committed           |
| **Diff**          | Line-by-line comparison showing exactly what changed |

### Step 4: Pull Request Lifecycle

Changes are submitted as **pull requests** that are automatically created and merged. This provides a clean, reviewable history where each PR represents a discrete set of changes to your org.

```
Hour 1: No audit trail entries → No action
Hour 2: Flow "Order Processing" modified
         → Retrieve flow metadata
         → Create PR with updated flow XML
         → Auto-merge with timestamp
Hour 3: No audit trail entries → No action
Hour 4: Apex class "AccountHelper" modified
         Validation rule on Contact updated
         → Retrieve both components
         → Create PR with both changes
         → Auto-merge with timestamp
```

***

## Setup and Reading the Output

Change Tracking requires a connected GitHub repository — use a **private** one, since the snapshots contain your Apex code, flow definitions, and object structures. For the repository setup, the OAuth connection, enabling the feature, and how to read the resulting diffs, see [Change Tracking](https://docs.pharos.ai/configuration-guide/change-tracking.md) and [GitHub](https://docs.pharos.ai/configuration-guide/integrations/github.md) in the Configuration Guide.

***

## Correlating Changes with Errors

One of the most powerful uses of Change Tracking is identifying whether a recent metadata change caused a new error. The workflow is straightforward:

1. **Error appears** in Pharos (new Issue or spike in occurrences)
2. **Check the timeline** — look at the Issue's "First Seen" date
3. **Review recent commits** — browse the GitHub repository for changes around that time
4. **Inspect the diff** — see exactly what was modified and assess whether it could have caused the error

```mermaid
graph TD
    A[Error: Issue Created May 15, 2:30 PM]
    B[Change Tracking: Commit May 15, 1:00 PM<br/>Validation rule modified on Account]
    C[These events align → investigate the validation rule change]
    A --> C
    B --> C
```

{% hint style="success" %}
**AI-Assisted Correlation:** Pharos's AI analysis can automatically scan the audit trail at the issue level and identify metadata changes that are likely candidates for causing a given error—saving you the manual investigation.
{% endhint %}

***

## Performance Considerations

Change Tracking is designed to be lightweight and non-intrusive.

| Aspect              | Detail                                                    |
| ------------------- | --------------------------------------------------------- |
| **Check frequency** | Hourly                                                    |
| **API consumption** | Minimal—only retrieves metadata when changes are detected |
| **Org impact**      | No impact on end-user transactions or governor limits     |
| **GitHub storage**  | Negligible—metadata files are small text files            |

{% hint style="info" %}
**Optimization for AI:** Beyond auditing, Change Tracking stores metadata in GitHub so that AI analysis features can read it directly—rather than making API calls to your org each time. This makes AI analysis both faster and more efficient.
{% endhint %}

→ [See which metadata types are tracked](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/tracked-metadata.md)

{% hint style="success" %}
**Next Step:** Review the [Tracked Metadata](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/tracked-metadata.md) page to see the full list of metadata components that Change Tracking monitors.
{% endhint %}
