Migrating OAuth Apps to GitHub Apps

This article provides guidelines for existing integrators who are considering migrating from an OAuth App to a GitHub App.

Reasons for switching to GitHub Apps

GitHub Apps are the officially recommended way to integrate with GitHub because they offer many advantages over a pure OAuth-based integration:

• Fine-grained permissions target the specific information a GitHub App can access, allowing the app to be more widely used by people and organizations with security policies than OAuth Apps, which cannot be limited by permissions.
• Short-lived tokens provide a more secure authentication method over OAuth tokens. An OAuth token does not expire until the person who authorized the OAuth App revokes the token. GitHub Apps use tokens that expire quickly, creating a much smaller window of time for compromised tokens to be in use.
• Built-in, centralized webhooks receive events for all repositories and organizations the app can access. Conversely, OAuth Apps require configuring a webhook for each repository and organization accessible to the user.
• Bot accounts don't consume a GitHub Enterprise Server seat and remain installed even when the person who initially installed the app leaves the organization.
• Built-in support for OAuth is still available to GitHub Apps using user-to-server endpoints.
• Dedicated API rate limits for bot accounts scale with your integration.
• Repository owners can install GitHub Apps on organization repositories. If a GitHub App's configuration has permissions that request an organization's resources, the org owner must approve the installation.
• Open Source community support is available through Octokit libraries and other frameworks such as Probot.
• Integrators building GitHub Apps have opportunities to adopt earlier access to APIs.

Converting an OAuth App to a GitHub App

These guidelines assume that you have a registered OAuth App. At a high level, you'll need to follow these steps:

1. Review the available API endpoints for GitHub Apps
2. Design to stay within API rate limits
3. Register a new GitHub App
4. Determine the permissions your app requires
5. Subscribe to webhooks
6. Understand the different methods of authentication
7. Direct users to install your GitHub App on repositories
8. Remove any unnecessary repository hooks
9. Encourage users to revoke access to your OAuth App
10. Delete the OAuth App

Review the available API endpoints for GitHub Apps

While the majority of REST API endpoints and GraphQL queries are available to GitHub Apps today, we are still in the process of enabling some endpoints. Review the available REST endpoints to ensure that the endpoints you need are compatible with GitHub Apps. Note that some of the API endpoints enabled for GitHub Apps allow the app to act on behalf of the user. See "User-to-server requests" for a list of endpoints that allow a GitHub App to authenticate as a user.

We recommend reviewing the list of API endpoints you need as early as possible. Please let Support know if there is an endpoint you require that is not yet enabled for GitHub Apps.

Design to stay within API rate limits

GitHub Apps use sliding rules for rate limits, which can increase based on the number of repositories and users in the organization. A GitHub App can also make use of conditional requests or consolidate requests by using the GraphQL API V4.

Register a new GitHub App

Once you've decided to make the switch to GitHub Apps, you'll need to create a new GitHub App.

Determine the permissions your app requires

When registering your GitHub App, you'll need to select the permissions required by each endpoint used in your app's code. See "