Skip to main content
The GitHub App is how Onyx gets access to GitHub repositories. Users start an Onyx branch 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 branches start from accessible repositories.
  • Receives webhook updates when repositories change.
  • Provides per-request access for private repository trees, blobs, diffs, and sync metadata.
Onyx does not store GitHub installation tokens. 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

Install or manage the Onyx GitHub App for your organization or account.
2

Choose repository access

Grant access to all repositories or selected repositories.
3

Return to Onyx

The setup callback links the installation to your active team.
4

Create the branch

Use /onyx ... or onyx branch create in the repository. Onyx provisions the project automatically on the first successful sync.

​
Troubleshooting

SymptomWhat to check
No installations appearConfirm the GitHub App was installed for the active Onyx team.
Repository missingManage GitHub App access and add the repository.
Repository sync failedConfirm the installation still has access and run project sync again.
Private repository fails to loadConfirm the repository belongs to the linked installation.