> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How to register your own GitHub App

> Register a GitHub App and obtain credentials to connect it to Nango

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.

<Steps>
  <Step title="Create a GitHub account">
    If you don't already have one, sign up for a [GitHub account](https://github.com/signup).
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configure callback URL (optional)">
    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**.

    Note: If your app doesn't need to act on behalf of a user, this field can be left blank.
  </Step>

  <Step title="Configure user authorization settings (optional)">
    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**.
  </Step>

  <Step title="Configure setup URL">
    1. Under **Setup URL**, enter the URL displayed on your Nango integration page.
    2. If you selected **Request user authorization (OAuth) during installation** in the previous step, you won't be able to enter a URL here.
    3. Do NOT select **Redirect on update** under **Post installation**.

    <Note>The Setup URL (displayed on your Nango integration page) needs to be added to your GitHub App configuration. This is not to be confused with the Callback URL that can stay empty.</Note>
  </Step>

  <Step title="Configure webhook settings">
    1. Keep **Active** selected to receive webhook events (recommended).
    2. Under **Webhook URL**, enter the webhook URL from your Nango integration configuration.
    3. Under **Webhook secret**, enter the webhook secret from your Nango integration configuration. This secret is used to verify webhook payloads from GitHub, so keep it secure and never expose it publicly.
    4. Under **SSL verification**, keep **Enable SSL verification** selected (recommended).
  </Step>

  <Step title="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.

    <Note>GitHub Apps use installation tokens that are scoped to specific repositories. The permissions and access are determined by the installation scope.</Note>
  </Step>

  <Step title="Subscribe to webhook events">
    If you kept **Active** selected for webhooks:

    1. Under **Subscribe to events**, select the webhook events you want your app to receive.
    2. Common webhook events include:
       * **Push**: When commits are pushed to a repository
       * **Pull request**: When pull requests are opened, closed, or modified
       * **Issues**: When issues are opened, closed, or modified
       * **Repository**: When repositories are created, deleted, or modified
  </Step>

  <Step title="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

    <Note>GitHub Apps can be installed at the organization level or the repository level. The permissions and access are determined by the installation scope.</Note>
  </Step>

  <Step title="Create the GitHub App">
    Click **Create GitHub App** to complete the registration process.
  </Step>

  <Step title="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.

    <Note>The App Private Key needs to be generated in your GitHub App settings (not to be confused with the Client Secrets).</Note>
  </Step>

  <Step title="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](https://github.com/apps/your-app-name)).
    3. You'll need both of these when configuring your integration in Nango.

    <Note>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](https://github.com/apps/nango-github-app)).</Note>
  </Step>

  <Step title="Next">
    Follow the [*Quickstart*](/getting-started/quickstart).
  </Step>
</Steps>

## 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](https://github.com/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](https://docs.github.com/en/apps).

***