> 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/integrations/github.md).

# Github

Configure the GitHub integration in Pharos Admin for change tracking and AI analysis.

The GitHub integration enables Pharos to commit metadata snapshots to a repository you control. This powers [Change Tracking](https://docs.pharos.ai/configuration-guide/change-tracking.md) — Pharos monitors your org's Setup Audit Trail for changes, retrieves the affected metadata, and commits the actual content to GitHub, giving you diffs, version history, and the ability to correlate errors with recent changes.

{% hint style="success" %}
**Why this matters:** Change Tracking is a prerequisite for full [Org Genie](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis/org-genie.md) capabilities. Without it, AI analysis can only answer questions about logs and issues — not about your metadata. With Change Tracking enabled, Org Genie reads from the GitHub repository to correlate errors with recent org changes, reducing API usage and speeding analysis.
{% endhint %}

{% hint style="info" %}
Pharos integrates with GitHub for **metadata version control** only. There is no integration with GitHub Issues at this time.
{% endhint %}

***

## Accessing GitHub Settings

1. Open the **Pharos** app → **Pharos Admin**
2. Select **Integrations** from the left-hand menu
3. Click **GitHub**

The page shows two sections: **Authentication Settings** at the top, and **Repository Settings** below.

Before configuration, the page shows the **Enable GitHub Integration** toggle in the off state:

![GitHub Authentication Settings — disabled state](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-22a933005fdea77f03146b8513f02949961da420%2Fgithub-auth-disabled.png?alt=media)

***

## Prerequisites

| Requirement         | Details                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **GitHub account**  | Personal or organization account with repository access                                                                                                                                                             |
| **Repository**      | A **private** repository for metadata snapshots — create one if needed ([GitHub docs: Creating a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository)) |
| **Push access**     | The authenticating user must have write access to the repository and branch                                                                                                                                         |
| **HTTPS clone URL** | The `.git` URL from the repository's **Code** dropdown (see below)                                                                                                                                                  |

***

## Authentication

Pharos supports two authentication methods. Enable the integration toggle, then choose one:

### Option 1: Connect via OAuth (Recommended)

> *Pharos will request GitHub access on your behalf once you authenticate with your GitHub credentials.*

1. Select **Connect via OAuth**
2. Click **Login to GitHub**
3. Authorize Pharos in the GitHub OAuth prompt
4. Once authorized, the **OAuth Token** field populates automatically

![GitHub OAuth — before login, token empty](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-46941d1e064078e90ef31bac20229bde2c28c90d%2Fgithub-auth-oauth-empty.png?alt=media)

After a successful login, the token appears (masked):

![GitHub OAuth — connected with token](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-49ded566dbde213bcc97ec500537e353bcc3d6f6%2Fgithub-auth-oauth-connected.png?alt=media)

Use **Reset** to clear the token and re-authenticate if needed.

### Option 2: Connect via API

> *Pharos will authenticate via an API token and a username provided by you.*

Use this option when OAuth is not feasible (e.g., service accounts, strict SSO policies, or GitHub Enterprise Server).

1. Select **Connect via API**
2. Generate a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) in GitHub with `repo` scope
3. Enter the token in the **API Token** field
4. Click **Test** to verify the connection

![GitHub API authentication — token field with Reset and Test buttons](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-a2e9864d396b61fc74e6e396a977a956a51fb726%2Fgithub-auth-api.png?alt=media)

***

## Repository Settings

After authentication, configure where Pharos commits metadata:

| Field                    | Description                                                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Repository HTTPS URL** | The HTTPS clone URL of your repository (e.g., `https://github.com/your-org/your-repo.git`). The authenticated user must have push access to this repository. |
| **Branch**               | The branch Pharos commits to (e.g., `main` or `master`). The user must have write access to this branch.                                                     |

![Repository Settings — help text explaining each field](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-c2997ab84cf4e1571fb2d1b924d8e69b188b5eb3%2Fgithub-repo-settings-help.png?alt=media)

### Finding the Repository HTTPS URL

In your GitHub repository, click the green **Code** button and copy the **HTTPS** URL:

![GitHub Code dropdown showing the HTTPS clone URL](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-e1beee399b9ff11953bbbf656cfa511a71a8c107%2Fgithub-clone-url.png?alt=media)

### Filled Example

![Repository Settings — configured with URL and branch](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-10c68413c2f6ce7f853bc2f94ada53c8e18d605c%2Fgithub-repo-settings-filled.png?alt=media)

Click **Save** to persist all settings.

***

## Setup Summary

{% stepper %}
{% step %}

### Enable and Authenticate

Turn on the **Enable GitHub Integration** toggle. Choose OAuth or API authentication and complete the connection.
{% endstep %}

{% step %}

### Create a Repository

If you don't have one yet, create a **private** repository in GitHub for metadata snapshots (e.g., `salesforce-metadata-audit`).
{% endstep %}

{% step %}

### Configure Repository Settings

Paste the **HTTPS clone URL** and specify the target **branch**. Click **Save**.
{% endstep %}

{% step %}

### Enable Change Tracking

Navigate to **Pharos Admin** → **Change Tracking** and enable it. This starts the hourly monitoring of your Setup Audit Trail. See [Change Tracking](https://docs.pharos.ai/configuration-guide/change-tracking.md) for details.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Connecting GitHub alone does **not** start metadata commits. You must also enable [Change Tracking](https://docs.pharos.ai/configuration-guide/change-tracking.md) separately.
{% endhint %}

***

## What Gets Committed

Once Change Tracking is enabled, Pharos monitors the Setup Audit Trail on an hourly basis. When changes are detected, it retrieves the affected metadata and commits it to your repository. Tracked metadata includes:

* **Apex** — classes, triggers
* **Flows** — flow definitions and process builders
* **Lightning Web Components**
* **Object metadata** — fields, validation rules
* Other key metadata types

Each change set arrives as an automatically created and merged pull request — a point-in-time snapshot of what changed, giving you full diff history in GitHub's interface. See [Tracked Metadata](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking/tracked-metadata.md) for the complete list.

***

## Repository Best Practices

| Practice                           | Why                                                                                                        |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Use a private repository**       | Your org's metadata — Apex code, flow definitions, object structures — should never be publicly accessible |
| **Use a dedicated repository**     | Keep Pharos metadata snapshots separate from your development source control                               |
| **Separate repos per environment** | Use different repositories for production vs. sandbox to avoid mixing metadata histories                   |
| **Don't manually edit commits**    | Pharos manages the commit history; manual changes may conflict with future snapshots                       |

***

## Sandbox Considerations

Use a **separate repository** for sandbox metadata. After a sandbox refresh:

1. Run the [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md) wizard with the **Sandbox Refresh** option
2. Re-authenticate the GitHub integration in the sandbox
3. Point Repository Settings to a sandbox-specific repository (e.g., `sandbox-metadata-snapshot`)

This keeps production and sandbox metadata histories distinct.

***

## Troubleshooting

| Issue                                     | Cause                                     | Resolution                                                                                   |
| ----------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| OAuth token expired                       | GitHub access revoked or token expired    | Click **Reset**, then **Login to GitHub** to re-authenticate                                 |
| API test fails                            | Invalid token or insufficient permissions | Verify the Personal Access Token has `repo` scope and is not expired                         |
| No commits appearing                      | Change Tracking not enabled               | Enable Change Tracking in Pharos Admin → Change Tracking                                     |
| "Repository not found"                    | Wrong URL or insufficient access          | Verify the HTTPS URL is correct and the authenticated user has push access                   |
| Push rejected                             | Branch protection rules                   | Ensure the Pharos user is allowed to push to the configured branch                           |
| Org Genie can't answer metadata questions | Change Tracking not running long enough   | Change Tracking needs time to accumulate history; it commits on detection, not retroactively |

***

## Related

* [Change Tracking](https://docs.pharos.ai/configuration-guide/change-tracking.md) — Enable and configure hourly metadata tracking
* [OpenAI Integration](https://docs.pharos.ai/configuration-guide/integrations/openai.md) — Required for AI Issue Analysis and Org Genie
* [GitHub: Creating a Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository) — GitHub's guide to creating repos
* [GitHub: Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) — Generate tokens for API authentication
