> ## Documentation Index
> Fetch the complete documentation index at: https://onyxresearch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub App Access

> Use the Onyx GitHub App to grant repository access for campaigns and code review.

The GitHub App is how Onyx gets access to GitHub repositories. Users start an
Onyx campaign from an accessible repository, and Onyx creates or reuses the
internal project row in the background.

## What the App Does

* Lists installations connected to your Onyx team.
* Lists repositories available to an installation.
* Creates or reuses internal projects when campaigns start from accessible repositories.
* Receives webhook updates when repositories or the installation itself change.
* Provides per-request access for private repository trees, blobs, diffs, and sync metadata.

Onyx does not store GitHub installation tokens. When connecting, GitHub also
asks you to authorize the app as your GitHub user; Onyx uses that one-time
authorization only to verify your GitHub account can access the installation
being linked, and never stores the user token.

GitHub installations and internal projects are scoped to the configured Onyx
GitHub App ID. This allows the development and production Onyx GitHub Apps to
both be installed on the same GitHub account or organization without sharing
installation records. Existing unscoped GitHub
links are intentionally not carried forward; reconnect GitHub access through the
active environment after applying the scoping migrations.

## Setup Flow

<Steps>
  <Step title="Connect GitHub">
    Click **Connect GitHub** in Settings → Integrations. The flow starts with
    a GitHub user authorization step that proves to Onyx which installations
    your account can access.
  </Step>

  <Step title="Choose the account or organization">
    If the app is already installed on accounts you can access, Onyx shows
    them so you can connect one to the current team directly — this is how
    several Onyx teams share one organization installation. To put the app
    somewhere new instead, continue to GitHub's installer, pick the account
    or organization, and grant access to all or selected repositories.
  </Step>

  <Step title="Return to Onyx">
    The flow lands back on Settings → Integrations with the result.
  </Step>

  <Step title="Create the campaign">
    Use `/onyx ...` or `onyx campaign setup` in the repository. Onyx provisions the project automatically when remote campaign setup resolves the linked repository.
  </Step>
</Steps>

## Managing Installations

Settings → Integrations lists each connected GitHub account with its
repository access mode and how many of the team's projects it backs.

* **Configure on GitHub** opens the installation's settings page on GitHub to
  change repository access, review permissions, or uninstall the app.
* **Disconnect** removes the connection from the current Onyx team only. Any
  team projects backed by the installation stop syncing and are marked as
  sync-failed; their history stays visible, and reconnecting the same GitHub
  account restores syncing. Disconnecting never uninstalls the app on GitHub.

The same GitHub account or organization can be connected to multiple Onyx
teams — each team links the installation separately, and each connection
requires a user with GitHub-side access to complete the flow. Disconnecting
one team leaves other teams' connections intact.

Changes made on GitHub's side propagate automatically through webhooks:
uninstalling the app removes the connection from every linked team and marks
their projects sync-failed, suspending pauses syncs until unsuspended, and
permission or repository-selection changes update what Onyx displays.

## Troubleshooting

| Symptom                                    | What to check                                                                           |
| ------------------------------------------ | --------------------------------------------------------------------------------------- |
| No installations appear                    | Confirm the GitHub App was installed for the active Onyx team.                          |
| Repository missing                         | Manage GitHub App access and add the repository.                                        |
| Repository sync failed                     | Confirm the installation still has access and run project sync again.                   |
| Private repository fails to load           | Confirm the repository belongs to the linked installation.                              |
| "Your GitHub account does not have access" | Connect with a GitHub user that can access the installation's repositories.             |
| "GitHub authorization failed"              | The one-time GitHub authorization expired or was reused — start the connect flow again. |