> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/get-started/onboarding-to-ox/source-control/github/github-app/creating-a-self-hosted-ox-github-app.md). # 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](/get-started/onboarding-to-ox/source-control/github.md). 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](/get-started/onboarding-to-ox/prerequisites-and-access/ox-broker.md) 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 **Developer settings** > **GitHub Apps**. 2. Select **New GitHub App**.
3. Configure the following settings. | Setting | Value | | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **GitHub App name** | `OX GitHub App` (for example, `OX Acme GitHub App`) | | **Description** | A short description, such as `OX GitHub App` | | **Homepage URL** | `` | | **Callback URL** |

\/github-app-installation-configure?appId=\
Note: Your OX Customer Success representative provides the values for appId and \. 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 | 4. Under **Webhook**, configure the following:
SettingValue
ActiveSelected
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.
SecretThe 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 * 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**.
2. Select **Create GitHub App**. ### Step 6: Generate the private key 1. On the GitHub App page, select **Generate a private key**.
2. 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**.
3. 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`). 2. Also note the App's **URL slug**, which appears in the GitHub URL after `/settings/apps/`: ``` /settings/apps/ ``` 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..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](https://claude.ai/get-started/onboarding-to-ox/prerequisites-and-access/ox-broker.md) is installed and configured to point at your GitHub Enterprise URL before completing the steps above. ### Related Topics * [GitHub connector](/get-started/onboarding-to-ox/source-control/github.md) * [OX Broker](/get-started/onboarding-to-ox/prerequisites-and-access/ox-broker.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ox.security/get-started/onboarding-to-ox/source-control/github/github-app/creating-a-self-hosted-ox-github-app.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.