Skip to main content
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

1

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.
2

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.
3

Return to Onyx

The flow lands back on Settings → Integrations with the result.
4

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.

​
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