Skip to main content
This guide shows you how to register your own GitHub App to obtain your OAuth credentials (App ID and Private Key). These are required to let your users grant your app access to their GitHub account.
1

Create a GitHub account

If you don’t already have one, sign up for a GitHub account.
2

Navigate to GitHub App settings

  1. In the upper-right corner of any page on GitHub, click your profile photo.
  2. Navigate to your account settings:
    • For an app owned by a personal account, click Settings.
    • For an app owned by an organization:
      • Click Your organizations.
      • To the right of the organization, click Settings.
  3. In the left sidebar, click Developer settings.
  4. In the left sidebar, click GitHub Apps.
  5. Click New GitHub App.
3

Configure basic app information

  1. Under GitHub App name, enter a name for your app. Choose a clear and short name (maximum 34 characters).
  2. Optionally, under Description, type a description of your app. Users will see this when installing your app.
  3. Under Homepage URL, type the full URL to your app’s website. If you don’t have a dedicated URL, you can use your GitHub repository URL or organization URL.
4

Configure callback URL

If your app needs to act on behalf of a user (generate a user access token):
  1. Under Callback URL, enter https://api.nango.dev/oauth/callback.
  2. You can add up to 10 callback URLs by clicking Add callback URL.
This field is required if you plan to select Request user authorization (OAuth) during installation in the next step, because that flow completes through the callback URL. It can be left blank otherwise.
5

Configure user authorization settings

  1. By default, Expire user authorization tokens is selected. GitHub recommends keeping this option enabled.
  2. If you want users to authorize your app when they install it, select Request user authorization (OAuth) during installation.
  3. If you want to use device flow to generate a user access token, select Enable Device Flow.
Item 2 decides which Nango integration you set up, and the next step depends on it. Leave it unselected for GitHub (App). Select it for GitHub (App OAuth), which authorizes the user and installs the app in one flow.
6

Configure setup URL

What you do here depends on the previous step.If you left Request user authorization (OAuth) during installation unselected, under Setup URL enter https://api.nango.dev/app-auth/connect. If you use a custom callback URL, take that URL and replace oauth/callback with app-auth/connect. Nango also shows the exact value on the integration page once you create it.If you selected Request user authorization (OAuth) during installation, GitHub disables the Setup URL field. There is nothing to enter, the connection completes through the callback URL and the installation webhook instead. Keep going with this guide, the remaining steps apply to both flows.In both cases, select Redirect on update under Post installation.
When the setup URL field is available, it is what completes the connection. GitHub sends the installation ID there after an install, and without it the app installs on GitHub but no connection appears in Nango.
The Setup URL is not to be confused with the Callback URL from the earlier step.
7

Configure webhook settings

Leave webhooks off for now. The webhook URL and secret both come from your Nango integration, and that integration needs the App ID and private key you generate later in this guide.
  1. Clear the Active checkbox. GitHub requires a webhook URL while Active is selected.
  2. Under SSL verification, keep Enable SSL verification selected (recommended).
You turn webhooks on in the last step, once Nango can show you both values.
8

Set app permissions

  1. Under Permissions, choose the permissions your app needs. For each permission, select the dropdown menu and click Read-only, Read & write, or No access.
  2. Select the minimum permissions necessary for your app’s functionality.
  3. Common permissions include:
    • Repository: Access to repositories
    • Issues: Access to issues
    • Pull requests: Access to pull requests
    • Workflows: Access to GitHub Actions workflows
    • Organization: Access to organization settings
Note: The permissions you select will determine what webhook events are available.
GitHub Apps use installation tokens that are scoped to specific repositories. The permissions and access are determined by the installation scope.
9

Set installation options

Under Where can this GitHub App be installed?, select:
  • Only on this account - For apps that only you or your organization will use
  • Any account - For apps that will be installed by other GitHub users or organizations
GitHub Apps can be installed at the organization level or the repository level. The permissions and access are determined by the installation scope.
10

Create the GitHub App

Click Create GitHub App to complete the registration process.
11

Generate a private key

After creating your GitHub App:
  1. On your GitHub App’s settings page, scroll down to the Private keys section.
  2. Click Generate a private key.
  3. A private key file will be downloaded to your computer. Store this file securely as GitHub will not store a copy.
  4. This private key will be needed when configuring your integration in Nango.
The App Private Key needs to be generated in your GitHub App settings (not to be confused with the Client Secrets).
12

Note your App ID and installation URL

  1. On your GitHub App’s settings page, note the App ID at the top of the page.
  2. Also note your App Public Link (e.g., https://github.com/apps/your-app-name).
  3. You’ll need both of these when configuring your integration in Nango.
When setting up a GitHub App, the App ID is made of numbers (e.g. 401953) and the App Public Link is the URL to your Github App public page (e.g. https://github.com/apps/nango-github-app).
13

Set up the integration in Nango

Create the integration in Nango and fill in the App ID, App Private Key and App Public Link you just collected. Use GitHub (App) if you left user authorization during installation unselected, and GitHub (App OAuth) if you selected it.GitHub (App OAuth) also needs the client ID and client secret. See GitHub App OAuth setup for those.Saving these lets Nango derive the webhook secret, which it cannot do before the integration exists.
14

Enable webhooks on your GitHub App

On your Nango integration page, copy the value under Webhook URL and the value under Webhook Secret. Then go back to your GitHub App settings:
  1. Select the Active checkbox under Webhooks.
  2. Under Webhook URL, paste the webhook URL from Nango.
  3. Under Webhook secret, paste the webhook secret from Nango. This is required. GitHub only signs payloads when the secret is set, and Nango verifies every payload it receives. Keep it secure and never expose it publicly.
  4. Under Subscribe to events, select the events you want your app to receive, such as Push, Pull request, Issues or Repository.
  5. Save the changes.
Nango rejects a webhook that arrives with no x-hub-signature-256 header, and it is not forwarded to your app. An app set up without the webhook secret looks correctly configured on GitHub but delivers nothing.
15

Next

Follow the Quickstart.

​
Important considerations

  • There are certain API methods that only work with an OAuth App that will not work with a GitHub App. Please check the Github documentation and look for a “Works with Github Apps” header under the endpoint.
  • Nango supports initiating a connection with a GitHub App using the frontend SDK, but not directly from the GitHub Marketplace. Therefore, you should encourage users to install your GitHub App from your product, rather than from the GitHub Marketplace directly. This is a limitation we plan to fix in the future.
  • GitHub Apps can use both REST and GraphQL APIs, but the available endpoints depend on the permissions configured for the app.
  • When making API requests with a GitHub App, you need to authenticate as the app installation, not as the app itself.
  • Rate limits for GitHub Apps are higher than for OAuth Apps and are based on the installation, not the user.
For more details on GitHub Apps, see GitHub’s documentation.