Connecting to your GitHub Enterprise (GHE) account for code reviews follows a different process than our standard GitHub App integration. Because GHE instances are self-hosted and may use a custom domain, a few prerequisite steps must be handled by our team to enable the connection for your workspace.
⚠️BEFORE YOU BEGIN⚠️
If your GitHub Enterprise instance has IP whitelisting enabled, please ensure you have allowed all of Gearset's static IP addresses. The list, which includes Clayton's addresses, can be found in our documentation here.
PREREQUISITE TO THIS SETUP: Before proceeding, please reach out to our team via the in-app support chat so we can request the necessary configuration for your account. When you contact us, let us know the URL of your GitHub Enterprise instance andwhich data residency option your Gearset account is using.
If you’re not sure about your data residency I'd refer to this doc: Which data center is your application hosted on? Which explains how to confirm it directly in Gearset.
Repo Setup
In your GitHub Enterprise instance, navigate to your organization's settings to create a new app: Organization settings > Developer settings > GitHub Apps > New GitHub App
Configure the app with the following details:
GitHub App name:
ClaytonHomepage URL:
https://app.clayton.io
Callback URL: This can be left empty.
Setup URL:
https://app.clayton.io/integrations/github/github-app-enterprise-[your-org-name]/installed(Note: Replace
[your-org-name]with your organization's name, e.g., "matterport")
Webhooks: The "Active" checkbox can be left unchecked; Code Review will manage webhooks automatically.
Repository permissions:
Commit statuses:
Read and WriteContents:
Read and WritePull requests:
Read and WriteWebhooks:
Read and Write
Organization permissions:
Members:
Read-only
Subscribe to events: Select all events.
Where can this GitHub App be installed?: Select the account or organization where you'd like to be able to install the Clayton app, or if you're not sure, select 'Any account'
Now, you'll connect Code Review to the app you just created.
Code Review Setup
Navigate to your connections settings in Code Review (Settings > Connections > Git Connections) and click + Add Connection.
Select the GitHub App @ [Your Org Name] connector that our team enabled for you.
A pop-up window will appear. Go to the
App settingspage of your newly created GitHub App and use the information there to fill in the following fields in the Code Review pop-up:GitHub Organization Name: The value from the
Owned bysection in the GitHub App settings (without the@prefix).App ID: The
App IDnumber from the GitHub App settings.Client ID: The
Client IDvalue from the GitHub App settings.Client Secret: Click
Generate a new client secretin GitHub and copy the generated secret into this field.
Private Key: In the "Private keys" section of the GitHub App settings, click Generate a private key. Download the .pem file that GitHub provides, and then upload it to Code Review by clicking Select Key File.
Now click OK on the Code Review popup window. You should be redirected to GitHub - accept the app installation and the connection should be created!
(FAQ)
Why do you recommend setting "Where can this GitHub App be installed?" to 'Any account'?
This setting determines which organizations or user accounts within your GitHub Enterprise instance can install and use the app. We recommend selecting Any account for maximum flexibility, as this ensures you can install the code review tool on any repository you need without future reconfiguration. However, if your security policy requires it, you can restrict the installation to a specific organization or user account (such as a dedicated service account).
How do the permissions for a GitHub App differ from an OAuth app?
While both are secure, GitHub Apps offer more granular control over permissions. Unlike a traditional OAuth app which often requests broad scopes of access, a GitHub App allows you to grant only the specific, "fine-grained" permissions required for the tool to function. This follows the principle of least privilege, ensuring the code review tool has the minimum access necessary to perform its tasks, such as reading repository contents and updating pull request statuses.
Does the app use my personal credentials? Should I use a service account to install it?
No, the GitHub App does not use your personal user credentials. It acts as its own distinct identity within GitHub, and actions performed by the tool (like comments on a pull request) will be attributed to the app itself, not the user who installed it.
However, for security and administrative best practices, we strongly recommend using a dedicated service account to create and install the GitHub App. This separates the app's administration from any individual user account, which is ideal for team environments.