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

# Change Tracking

Learn about change tracking and why having a historical backup of key metadata is valuable for your Salesforce org.

Every Salesforce org evolves—flows get updated, validation rules change, Apex classes are refactored, fields are added or removed. When something breaks, one of the first questions is always: *what changed?*

Pharos Change Tracking answers that question automatically by maintaining a continuous, version-controlled history of your org's metadata in a GitHub repository.

{% hint style="info" %}
**Expanded Audit Trail:** Think of Change Tracking as an expanded version of Salesforce's native Setup Audit Trail—but one that captures the actual content of what changed, not just that a change occurred.
{% endhint %}

***

## The Problem

Most Salesforce orgs have no meaningful change log at all. Changes happen daily—a flow is updated, a validation rule is tweaked, a field is added—and there's no record of what the component looked like before.

Salesforce's native Setup Audit Trail tells you *that* a change was made, but not *what* specifically changed within a component. When a flow is modified or an Apex class is updated, you see a single line entry—no diff, no before-and-after comparison, no way to roll back.

| Gap                                 | Impact                                                                                                      |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **No content-level history**        | You know a flow was modified, but not which elements changed or what the previous version looked like       |
| **No visibility into direct edits** | Changes made through Setup bypass CI/CD pipelines entirely and leave no detailed trace                      |
| **No cross-team awareness**         | When multiple admins and developers are working in the same org, changes happen without anyone else knowing |
| **No correlation to errors**        | When something breaks, there's no easy way to connect the error to a recent metadata change                 |

This lack of auditability creates a blind spot. Errors surface, but tracing them back to the change that caused them becomes a manual, time-consuming investigation.

***

## How Pharos Solves It

Change Tracking bridges this gap by connecting your Salesforce org to a GitHub repository and automatically committing metadata snapshots whenever changes are detected.

```mermaid
graph TD
    A[Salesforce Org<br/>Setup Audit Trail]
    B[Pharos Change<br/>Tracking Engine]
    C[GitHub Repository - Private<br/>Pull Requests • Diffs • Timestamped History]
    A -->|Hourly check| B
    B -->|Commit changed metadata| C
```

The result is a **snapshotted timeline** of every meaningful metadata change—who changed it, when it happened, and exactly what was modified. All of it is browsable through GitHub's familiar interface.

{% hint style="success" %}
**Full Auditability, Zero Overhead:** Change Tracking gives your org something it's never had—a complete, content-level history of metadata changes that requires no manual effort to maintain.
{% endhint %}

***

## Key Benefits

### Visibility Across the Team

When multiple admins, developers, and consultants are making changes to the same org, it's easy to lose track. Change Tracking ensures every modification is recorded automatically—regardless of who made it or whether it went through a formal deployment process.

### Root Cause Correlation

When errors start appearing, you can look at recent metadata commits to identify changes that may have caused the problem. The timestamped commit history lines up directly with your error timeline in Pharos.

### AI-Powered Analysis

Change Tracking serves as the foundation for Pharos's advanced AI analysis capabilities. Rather than pulling metadata from your org on every analysis request (which consumes API calls), the AI reads directly from the GitHub repository—making analysis faster and more efficient.

{% hint style="info" %}
**AI Dependency:** The advanced AI analysis features rely on Change Tracking to access your org's metadata. Enabling Change Tracking now means you're ready to take advantage of these capabilities as they become available.
{% endhint %}

### Compliance and Auditability

For organizations with compliance requirements, having a complete, immutable record of metadata changes provides an audit trail that goes far beyond what Salesforce natively offers.

***

## Getting Started

Setting up Change Tracking involves two steps:

1. **Connect GitHub** — Link your GitHub account through the Pharos Integrations settings
2. **Enable Change Tracking** — Select a repository and branch, then turn on the feature

## In This Section

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>⚙️ Mechanism</strong></td><td>How Pharos monitors the audit trail and commits metadata snapshots to GitHub.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/mechanism.md">Mechanism</a></td></tr><tr><td><strong>📊 Tracked Metadata</strong></td><td>The list of metadata types that Pharos tracks as part of change tracking.</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/tracked-metadata.md">Tracked Metadata</a></td></tr></tbody></table>

{% hint style="success" %}
**Next Step:** Read about the [Mechanism](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/mechanism.md) to understand how Change Tracking monitors your org and commits changes to GitHub.
{% endhint %}
