Self-managed: Connect users via GitHub OAuth

Cortex attempts to map users to your GitHub organization, but you may need to use the GitHub OAuth flow to connect a GitHub user to a Cortex user.

Setup Instructions​

Before getting started: Make sure you have already set up a form of GitHub authentication (either via GitHub App or personal access token).

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 “OAuth Apps” -> "New OAuth App"

3. Set the following settings:

   1. Authorization callback URL: <FRONTEND HOST>/oauth/internal/github

   2. Application name and Homepage URL can be set to whatever you'd like

4. Click "Register application"

5. Copy down the listed "Client ID"

6. Click "Generate a new client secret" and copy this down as well

Connect your Cortex instance​

You'll need to configure your on-prem deployment to be able to talk your GitHub OAuth App.

1. 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.

2. Add the following keys to your secret (make sure they're base64 encoded with no extraneous at the end):

   1. GITHUB_OAUTH_CLIENT_ID (from step 5)

   2. GITHUB_OAUTH_CLIENT_SECRET (from step 6)

   3. If using a self-hosted GitHub Enterprise instance

      1. If you didn't configure it during GitHub App setup, set GITHUB_URL to your GitHub enterprise API endpoint

      2. Set GITHUB_OAUTH_URL to <GITHUB_URL>/login/oauth/authorize

      3. Set GITHUB_OAUTH_ACCESS_TOKEN_URL to <GITHUB_URL>/login/oauth/access_token

3. Restart Cortex backend deployment in k8s

Install the App​

Once your backend has restarted, you're ready to start connecting users.

Navigate to <FRONTEND HOST>/admin/settings/github-connection with a Cortex account you'd like to connect to a GitHub account.

Follow the OAuth flow.

Your account should now be connected and all of our GitHub integration magic should work nicely with the connected Cortex account!