# Self-managed GitHub App

This guide explains how to configure the GitHub integration for a [Cortex self-managed](/self-managed.md) account. When integrating with a self-managed Cortex instance, you must configure your own app and connect it to your Cortex instance.

If you are looking for instructions on configuring a GitHub integration for your Cortex cloud workspace, please see [Integrations > GitHub](/ingesting-data-into-cortex/integrations/github.md).

## Setup Instructions[​](https://docs.cortex.io/docs/self-managed/guides/github-app#setup-instructions) <a href="#setup-instructions" id="setup-instructions"></a>

### Create the App[​](https://docs.cortex.io/docs/self-managed/guides/github-app#create-the-app) <a href="#create-the-app" id="create-the-app"></a>

First, you'll need to create a GitHub App in your GH organization.

1. Go to `https://github.com/organizations/<org>/settings/apps`
2. Click on “New GitHub App”
3. Set the following settings:
   * Callback URL: `https://<FRONTEND HOST>/github/redirect`
   * Disable "Expire user authorization tokens," since Cortex does not support this OAuth workflow yet
   * Request user authorization (OAuth) during installation: true
   * Webhook: active = true
   * Webhook URL: `https://<API HOST>/api/internal/v1/github/webhook`
   * Webhook secret: Random string (save this somewhere)
   * Enable SSL verification: true
4. Click “Generate a private key” and save the key.
5. Under “Permissions & Events” for repository permissions:
   * Single file: R+W to path cortex.yaml
   * Dependabot alerts: R
   * Actions: R
   * Metadata: R
   * Code scanning alerts: R
   * Administration: R+W
   * Checks: R+W
   * Commit statuses: R+W
   * Contents: R+W (Write is only needed if using the Scaffolder)
   * Pull Requests: R+W (Write is needed if you're using a [Scaffolder](/streamline/workflows/scaffolder.md))
   * Secrets: R+W
   * Workflows: R+W
6. Under “Permissions & Events” for organization permissions:
   * Members: R
7. Subscribe to events: Check suite, Push (For GitOps). Note: these options will only show up when `Contents` permission is selected earlier.
8. Save the application

### Install the App[​](https://docs.cortex.io/docs/self-managed/guides/github-app#install-the-app) <a href="#install-the-app" id="install-the-app"></a>

Visit your app page, for example `https://github.com/organizations/<org>/settings/apps/<app>/installations`. Install the app into the org, and you should be good to go!

## Verification[​](https://docs.cortex.io/docs/self-managed/guides/github-app#verification) <a href="#verification" id="verification"></a>

You can verify that Cortex is able to reach GitHub by clicking "Import New Service" on the homepage, and checking whether your repositories are being discovered.

## Setup Instructions (Legacy)[​](https://docs.cortex.io/docs/self-managed/guides/github-app#setup-instructions-legacy) <a href="#setup-instructions-legacy" id="setup-instructions-legacy"></a>

#### Create the App (Legacy)[​](https://docs.cortex.io/docs/self-managed/guides/github-app#create-the-app-legacy) <a href="#create-the-app-legacy" id="create-the-app-legacy"></a>

Follow the same steps as above to set up your GitHub App.

#### Connect your Cortex instance (Legacy)[​](https://docs.cortex.io/docs/self-managed/guides/github-app#connect-your-cortex-instance-legacy) <a href="#connect-your-cortex-instance-legacy" id="connect-your-cortex-instance-legacy"></a>

This step is no longer necessary, but you can configure your on-prem deployment with environment variables to talk your GitHub App.

1. Prepare the private key stored in step 4 in the previous section by replacing all whitespaces with , for example with `awk '{printf "%s\\n", $0}' gh-private-key.pem | pbcopy`
2. Create a k8s secret and add the secret in your `values.yaml` file for the Helm chart. You may already have a secret set up if you had configured a persistent store previously, so be sure to verify in your Helm chart.
3. Add the following keys to your secret (make sure they're base64 encoded with no extraneous at the end):
   * `GITHUB_APPLICATION_ID` (from the app page)
   * `GITHUB_CLIENT_ID` (from the app page)
   * `GITHUB_CLIENT_SECRET` (generated on the app page by clicking "Generate a new Client Secret")
   * `GITHUB_SECRET` (webhook secret defined in Step 3.6)
   * `GITHUB_PRIVATE_KEY` (the secret you just modified in step 2)
   * Optionally, if you're using self-hosted GitHub Enterprise, set `GITHUB_URL` to your *GitHub API endpoint*. This usually ends with `/api/v3`
4. Restart Cortex backend deployment in k8s

#### Install the App (Legacy)[​](https://docs.cortex.io/docs/self-managed/guides/github-app#install-the-app-legacy) <a href="#install-the-app-legacy" id="install-the-app-legacy"></a>

Once your backend has restarted, you're ready to install the app.

Note: Make sure you're logged in on your Cortex application before triggering this install.

Follow the same steps as above to install the app.


---

# Agent Instructions: 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:

```
GET https://docs.cortex.io/self-managed/features/integrations/github.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.