Skip to main content
This guide explains how to configure the GitHub integration for a Cortex self-managed 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.

​
Setup Instructions↗

​
Create the App↗

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)
    • 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↗

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↗

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)↗

​
Create the App (Legacy)↗

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

​
Connect your Cortex instance (Legacy)↗

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)↗

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.
Last modified on September 9, 2026