GitHub

Instructions for setting up GitHub authentication integration for NocoDB

This document provides instructions for setting up the GitHub authentication integration for NocoDB.

Environment Variables

To enable OAuth2 authentication with GitHub, you need to set up the following environment variables:

Step 1: Create a GitHub OAuth App

1. Log in to your GitHub account
2. Navigate to Settings > Developer settings > OAuth Apps
3. Click on "New OAuth App"
4. Fill out the form:

• Application name : Your application name (e.g., "NocoDB")
• Homepage URL : Your application's homepage URL
• Application description : (Optional) Brief description of your app
• Authorization callback URL : The URL where GitHub will redirect users after authorization (e.g., https://your-nocodb-instance.com/)
• Icon : (Optional) Upload an icon for your application

1. Click "Register application"

Step 2: Get Client ID and Client Secret

After registering your OAuth App, you'll be provided with:

• Client ID
• Client Secret (click "Generate a new client secret" to create one)

Step 3: Set Environment Variables

Configure your NocoDB instance with the following environment variables:

INTEGRATION_AUTH_GITHUB_CLIENT_ID=your_github_client_id
INTEGRATION_AUTH_GITHUB_CLIENT_SECRET=your_github_client_secret
INTEGRATION_AUTH_GITHUB_REDIRECT_URI=your_redirect_uri

Where:

• your_github_client_id : The Client ID from your GitHub OAuth App
• your_github_client_secret : The Client Secret from your GitHub OAuth App
• your_redirect_uri : The callback URL you specified when creating the OAuth App (e.g., https://your-nocodb-instance.com/api/v1/integrations/auth/github/callback)

OAuth Scopes

The GitHub integration requests the following GitHub scopes:

• read:user : Read-only access to user profile data
• repo : Full control of repositories

GitHub App Installation

As an alternative to an OAuth App, a deployment can register a GitHub App. Users then install that App on the organization or account whose repositories they want to connect, instead of authorizing an OAuth App. NocoDB stores only the installation identifier and mints a short-lived installation token from the App's private key each time it calls GitHub.

Step 1: Create a GitHub App

1. Navigate to Settings > Developer settings > GitHub Apps
2. Click on "New GitHub App"
3. Set the callback URL to the same value you use for INTEGRATION_AUTH_GITHUB_REDIRECT_URI
4. Grant the App the repository permissions your integrations need
5. Click "Create GitHub App", then "Generate a private key" to download the key in PEM format

Step 2: Set Environment Variables

INTEGRATION_AUTH_GITHUB_APP_ID=your_github_app_id
INTEGRATION_AUTH_GITHUB_APP_SLUG=your_github_app_slug
INTEGRATION_AUTH_GITHUB_APP_PRIVATE_KEY=your_github_app_private_key

Where:

• your_github_app_id : The App ID shown on the App's settings page
• your_github_app_slug : The App's URL slug, the last segment of https://github.com/apps/<slug>
• your_github_app_private_key : The contents of the PEM private key. Newlines may be escaped as \n

All three variables, plus INTEGRATION_AUTH_GITHUB_REDIRECT_URI , must be set. When they are, the GitHub connection form offers GitHub App alongside the existing authentication types, and selecting it opens https://github.com/apps/<slug>/installations/new so the user can pick which repositories to grant. Testing the connection lists the repositories the installation can reach.

Availability

• App Sync is available on NocoDB Cloud (Plus plan and above) and licensed self-hosted deployments (Business plan and above). This page covers OAuth app setup for self-hosted deployments; on NocoDB Cloud these OAuth apps are preconfigured.

Related pages

• Bitbucket : Instructions for setting up Bitbucket authentication integration for NocoDB
• GitLab : Instructions for setting up GitLab authentication integration for NocoDB
• Google Calendar : Instructions for setting up Google Calendar authentication integration for NocoDB
• Linear : Instructions for setting up Linear authentication integration for NocoDB
• Outlook Calendar : Instructions for setting up Outlook Calendar authentication integration for NocoDB