Skip to main content

Connecting users via GitHub OAuth

Cortex tries its best to map its users to those from your GitHub organization, but sometimes it needs some extra help. If you want to directly connect a GitHub user to a Cortex user, our GitHub OAuth flow is the way to go!

Setup Instructions​

Please make sure you have already set up a form of GitHub authentication (either via GitHub App or personal access token) prior to going further with this guide.

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 \n 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!