Connecting with Self-Hosted OX GitHub App

Connect using a self-hosted GitHub App

If you run GitHub Enterprise Server in your own environment, you cannot install the public OX GitHub App from github.com. Instead, you register a dedicated OX GitHub App directly inside your GitHub Enterprise instance and share its credentials with OX Security.

This page describes how to create and configure that GitHub App. For an overview of the standard (SaaS) GitHub App flow and other connection methods, see GitHub.

Use this connection method when:

• Your source code is hosted on GitHub Enterprise Server rather than github.com.

• You want to authenticate using a GitHub App.

• Your GitHub Enterprise Server is reachable from OX directly or through an OX Broker.

Process overview

Connecting a self-hosted GitHub App requires actions from both your organization and OX.

1. Generate a webhook secret.

2. Create and configure a GitHub App in your GitHub Enterprise Server.

3. Configure the required permissions and subscribed events.

4. Generate the app credentials.

5. Share the required app details with OX.

6. OX registers the GitHub App, completes the required backend configuration, and enables GitHub App support for your organization.

7. Install the GitHub App in your GitHub Enterprise organization.

8. Connect GitHub in OX and select the repositories and branches to scan.

Before you begin

Make sure you have the following:

Requirement	Description
GitHub Enterprise access	Organization owner permissions for the GitHub Enterprise organization where the app will be registered.
GitHub Enterprise URL	The URL of your GitHub Enterprise Server.
OX Broker (if applicable)	If your GitHub Enterprise instance is not reachable from the public internet, deploy the OX Broker in your environment first.
OX Customer Success contact	OX provides the instance-specific values required during the setup, including the callback URL, webhook URL, and appId.

Step 1: Generate a webhook secret

The webhook secret is a 40-character random string that GitHub uses to sign webhook payloads sent to OX.

Generate the secret locally.

Linux or Windows (WSL/Git Bash)

tr -dc a-z0-9 </dev/urandom | head -c 40; echo

macOS

LC_ALL=C tr -dc 'a-z0-9' < /dev/random | head -c 40

Note

Generate a new webhook secret for each GitHub App. Do not reuse a secret from another application.

Step 2: Create the GitHub App

1. In GitHub Enterprise Server, go to Settings > Developer settings > GitHub Apps.

2. Select New GitHub App.

1. Configure the following settings.

Setting	Value
GitHub App name	OX <customer-name> GitHub App (for example, OX Acme GitHub App)
Description	A short description, such as OX <customer-name> GitHub App
Homepage URL	<ox-instance-url>
Callback URL	<ox-instance-url>/github-app-installation-configure?appId=<customer-name> Note: Your OX Customer Success representative provides the values for appId and <customer-name>. These values must exactly match the configuration registered on the OX side.
Expire user authorization tokens	Cleared
Request user authorization (OAuth) during installation	Selected
Enable Device Flow	Cleared
Setup URL (optional)	Leave empty
Redirect on update	Selected

1. Under Webhook, configure the following:

Setting	Value
Active	Selected
Webhook URL	<ox-instance-url>/api/githubapp/<customer-name>/webhooks Note: Your OX Customer Success representative provides the values for <ox-instance-url> and <customer-name>. These values must exactly match the configuration registered on the OX side.
Secret	The webhook secret generated in Step 1

Step 3: Configure permissions

Configure the GitHub App permissions as shown below. Leave every permission that is not listed set to No access.

Repository permissions

Permission	Access
Actions	Read and write
Administration	Read and write
Agent secrets	No access
Agent tasks	No access
Agent variables	No access
Artifact metadata	No access
Attestations	No access
Checks	Read and write
Code quality	No access
Code scanning alerts	Read-only
Codespaces	No access
Codespaces lifecycle admin	No access
Codespaces metadata	No access
Codespaces secrets	No access
Commit statuses	Read-only
Contents	Read and write
Copilot agent settings	No access
Custom properties	No access
Dependabot alerts	Read-only
Dependabot secrets	No access
Deployments	Read-only
Discussions	No access
Environments	No access
Issues	Read and write
License compliance alerts	No access
Merge queues	No access
Metadata	Read-only (mandatory)
Packages	Read-only
Pages	Read-only
Projects	Read-only
Pull requests	Read and write
Repository security advisories	No access
Secret scanning alert dismissal requests	No access
Secret scanning alerts	Read-only
Secret scanning push protection bypass requests	No access
Secrets	No access
Single file	No access
Variables	No access
Webhooks	Read-only
Workflows	Read and write

Organization permissions

Permission	Access
Administration	Read-only
Blocking users	Read-only
Custom repository roles	Read-only
Events	Read-only
Members	Read and write
Projects	Read-only
Self-hosted runners	Read-only
Webhooks	Read-only

Account permissions

Leave all account permissions set to No access.

Step 4: Subscribe to events

Select only the following events:

• Meta

• Check run

• Check suite

• Merge group

• Pull request

• Push

• Repository

Leave all other events cleared.

Step 5: Choose where the app can be installed

1. Under Where can this GitHub App be installed?, select Only on this account.

1. Select Create GitHub App.

Step 6: Generate the private key

1. On the GitHub App page, select Generate a private key.

1. Save the downloaded .pem file in a secure location.

GitHub displays the private key only once. If you lose it, you must generate a new one.

Step 7: Generate the client secret

1. On the GitHub App page, scroll to Client secrets.

2. Select Generate a new client secret.

1. Copy the generated value immediately.

GitHub displays the client secret only once.

Step 8: Collect the app identifiers

1. From the App's settings page, copy the following values from the About section:

• App ID (numeric, for example, 941975).

• Client ID (for example, Iv23liJFWBwZiGNQIrJV).

1. Also note the App's URL slug, which appears in the GitHub URL after /settings/apps/:

/settings/apps/<url-slug>

For example:

https://github.example.com/settings/apps/ox-acme-github-app

The URL slug is:

ox-acme-github-app

Step 9: Share the values with OX

Provide the following information to your OX Customer Success representative through a secure channel.

Value	Source
GitHub Enterprise server instance URL	The full URL of your GitHub Enterprise instance (for example, https://github.<your-company>.com).
Webhook secret	The 40-character string generated in Step 1.
Private key	The .pem file downloaded in Step 6.
App ID	From the App's About section (Step 8).
Client ID	From the App's About section (Step 8).
Client secret	The value generated in Step 7.
URL slug	From the App's GitHub URL (Step 8).

Note:

Treat the private key, client secret, and webhook secret as sensitive credentials. Share them only through a secure channel.

Step 10: Install the App and Complete the Connection in OX

After OX confirms that your App has been registered on the OX side:

1. In GitHub Enterprise, open the App's settings page and select Install App.

2. Choose the organization to install the App on, and select All repositories or Only select repositories based on what you want OX to scan.

3. Select Install & Authorize.

4. In the OX platform, go to Connectors and select GitHub > GITHUB APP. The list of repositories from the installation appears.

5. Select the repositories you want OX to scan and select SAVE.

6. (Optional) Select branches to scan within those repositories.

If your GitHub Enterprise instance is not reachable from the public internet, make sure the OX Broker is installed and configured to point at your GitHub Enterprise URL before completing the steps above.

Related Topics

• GitHub connector

• OX Broker