Registering GitHub Apps

You can create a GitHub App under your personal account or under any organization you have administrative access to.

Note: GitHub Apps are only compatible with the REST API v3 at this time.

  1. In the upper-right corner of any page, click your profile photo, then click Settings. Settings icon in the user bar
  2. In the left sidebar, click GitHub Apps. GitHub Apps section
  3. Click Register a new GitHub App. Button to register a new GitHub App
  4. In "GitHub App name", type the name of your app.

    Tip: Give your app a clear and succinct name. A slugged version of your app's name will be shown in the user interface when your integration takes an action.

    Field for the name of your GitHub App

  5. Optionally, in "Description", type a description of your app that users will see. Field for a description of your GitHub App

  6. In "Homepage URL", type the full URL to your app's website. Field for the homepage URL of your GitHub App
  7. In "User authorization callback URL", type the full URL to redirect to after a user authorizes an installation. This URL is used if your app needs to identify and authorize user-to-server requests. Field for the user authorization callback URL of your GitHub App
  8. Optionally, if additional setup is required after installation, in "Setup URL", type a URL to redirect users to after they install your app. Field for the setup URL of your GitHub App
  9. In "Webhook URL", type the URL that events will POST to. Each app receives its own webhook which will notify you every time the app is installed or modified, as well as any other events the app subscribes to. Field for the webhook URL of your GitHub App
  10. Optionally, in "Webhook Secret", type an optional secret token used to secure your webhooks.

    Note: We highly recommend that you set a secret token. For more information, see "Securing your webhooks."

    Field to add a secret token for your webhook

  11. In "Permissions", choose the permissions your app will request. For each type of permission, use the drop-down menu and click Read-only, Read & write, or No access. Various permissions for your GitHub App

  12. To choose where the app is installed, select either Only on this account or Any account. Installation options for your GitHub App
  13. Click Create GitHub App. Button to create your GitHub App

Generating a private key

After a GitHub App is registered, you'll need to generate a private key. The private key will be used to sign access token requests. To generate a private key, click on your app's name, then click the Generate private key button.

Note: A private key in PEM format will be downloaded to your computer. Ensure that you store this as GitHub only stores the public portion of the key.