> 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/configuration-guide/change-tracking.md).

# Change Tracking

Configure change tracking to maintain a version-controlled history of metadata changes in GitHub.

When something breaks in production, one of the first questions is: *what changed?* Salesforce's Setup Audit Trail tells you *that* a change occurred — but not *what* specifically changed in the code or configuration. Change Tracking fills that gap by committing the actual metadata content to a GitHub repository, giving you diffs, history, and the ability to correlate errors with recent changes.

**Navigate:** Pharos App → **Pharos Admin** → **Change Tracking**

![Change Tracking — disabled state](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-d14b04f91c8a11cceb891fc023aee8240fa9f292%2Fchange-tracking-disabled.png?alt=media)

{% hint style="info" %}
For conceptual overview and benefits, see [Change Tracking](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking.md).
{% endhint %}

***

## Prerequisites

| Requirement            | Details                                                                                                                      |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **GitHub connected**   | [GitHub integration](https://docs.pharos.ai/configuration-guide/integrations/github.md) must be configured and authenticated |
| **Private repository** | A dedicated private repo for metadata snapshots — create one if needed                                                       |
| **Admin access**       | System Administrator or equivalent in Salesforce                                                                             |

{% hint style="warning" %}
**Always use a private repository.** Your org's metadata — Apex code, flow definitions, object structures — should not be publicly accessible. When creating the repository, set visibility to **Private**.
{% endhint %}

***

## Enabling Change Tracking

{% stepper %}
{% step %}

### Connect GitHub

Navigate to [Integrations → GitHub](https://docs.pharos.ai/configuration-guide/integrations/github.md) and authenticate via OAuth or API key. Configure the repository HTTPS URL and branch (typically `main`).
{% endstep %}

{% step %}

### Enable Change Tracking

Back on the Change Tracking page, turn the **Enable Change Tracking** toggle on.

![Change Tracking — enabled with Push Now option](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-20b3847f54373701f7f9d2a92e68f58c2e83677f%2Fchange-tracking-enabled.png?alt=media)
{% endstep %}

{% step %}

### Initial Push

On first enable, Pharos performs a **full metadata push** — committing the current state of all tracked metadata to the repository. This establishes the baseline snapshot.
{% endstep %}
{% endstepper %}

***

## How It Works

Once enabled, Change Tracking operates on an **hourly cycle**:

1. Pharos checks the Salesforce **Setup Audit Trail** for entries in the last hour
2. If changes are detected, Pharos retrieves the current state of the **affected metadata** from your org
3. The changed metadata is submitted to your GitHub repository as a pull request — automatically created and merged — with a diff showing exactly what changed
4. If no audit trail entries exist for that hour, no action is taken

The **initial push** commits all tracked metadata to establish a baseline. After that, only **incremental changes** are committed — keeping API consumption minimal and the history meaningful. See [Mechanism](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/mechanism.md) for why the audit trail is used as the change-detection signal.

### Manual Push

The **Push Now** button triggers an immediate metadata push outside the hourly schedule. Use this when you've just made changes and want them committed right away without waiting for the next hourly cycle.

***

## Tracked Metadata

Pharos tracks the components most likely to cause issues when changed — Apex classes and triggers, flows, workflow rules, objects and fields, Aura and Visualforce components, custom metadata types, remote site settings, approval processes, connected apps, and named credentials. Profiles, permission sets, reports, dashboards, and static resources are **not** tracked.

In the repository these are organized under `main/default/`, one folder per metadata type. For the complete list with what each folder captures, see [Tracked Metadata](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/tracked-metadata.md).

***

## Reading the Output

All change tracking output lives in your GitHub repository. Each auto-merged pull request represents a set of metadata changes detected during an hourly cycle (or manual push), so you can open any one to see exactly which lines changed, browse a component as it existed at any point in time, diff any two points in your org's history, or search across components.

{% hint style="info" %}
Reading metadata diffs requires some familiarity with the underlying formats. Apex class diffs are straightforward for developers. Flow metadata XML may take some getting used to for admins, but the key information — what component changed and how — is always visible.
{% endhint %}

***

## AI Analysis and Org Genie

Change Tracking serves a dual purpose beyond auditing — it powers Pharos's AI capabilities.

[Org Genie](https://docs.pharos.ai/configuration-guide/integrations/openai.md) requires Change Tracking to answer questions about your metadata. Without it, Org Genie can only analyze logs and issues. With Change Tracking enabled, the AI can:

* **Read actual source code** of the Apex class or flow that generated an error
* **Examine recent changes** to determine if a modification caused a new issue
* **Analyze dependencies** between components to understand the blast radius of a change

The metadata in GitHub is indexed and vectorized so that AI analysis reads directly from the repository rather than making API calls to your org — faster, cheaper, and with no impact on governor limits.

{% hint style="success" %}
**Recommended:** Enable Change Tracking before heavy Org Genie use. The longer it runs, the more historical context the AI has access to. Turning it on today means you can't ask "what changed last month?" until the history accumulates.
{% endhint %}

***

## Troubleshooting

| Issue                                | Cause                                     | Resolution                                                                                              |
| ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Change Tracking toggle not available | GitHub not connected                      | Configure [GitHub integration](https://docs.pharos.ai/configuration-guide/integrations/github.md) first |
| No commits appearing                 | No audit trail entries detected           | Pharos only commits when changes are detected; make a metadata change and wait one hour                 |
| Want immediate commit                | Hourly cycle hasn't run yet               | Use the **Push Now** button                                                                             |
| Repository appears empty             | Initial push may still be running         | Wait for the initial full push to complete; check back in a few minutes                                 |
| AI can't answer metadata questions   | Change Tracking not enabled or too recent | Enable Change Tracking and allow time for history to accumulate                                         |

***

## Related

<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>🐙 GitHub Integration</strong></td><td>Connect and authenticate GitHub</td><td><a href="https://docs.pharos.ai/configuration-guide/integrations/github.md">Github</a></td></tr><tr><td><strong>⚙️ Change Tracking Mechanism</strong></td><td>How commits are created and structured</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>Full list of metadata types monitored</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>
