About GitHub Apps
A GitHub App is a type of integration that you can build to interact with and extend the functionality of GitHub. You can build a GitHub App to provide flexibility and reduce friction in your processes, without needing to sign in a user or create a service account.
Common use cases for GitHub Apps include:
- Automating tasks or background processes
- Supporting "Sign in with GitHub," which allows users to sign in with their GitHub account to provide their identity in your ecosystem
- As a developer tool, allowing users to work with GitHub by signing into your GitHub App, which can then act on their behalf
- Integrating your tool or external service with GitHub
GitHub Apps are independent actors within GitHub. A GitHub App acts on its own behalf, which means that you don't need to maintain a bot or service account as a separate user. They can also authenticate as a user and act on the user's behalf, using the permissions granted to it.
If you want your app to respond to events on GitHub, your app should subscribe to webhooks. For example, you may want your app to leave a comment when a pull request is opened. For more information, see "Using webhooks with GitHub Apps."
During development, you can run your app locally for development. Once the app is ready for production use, you should deploy your app to a dedicated server. For example, you can use Azure App Service.
Permissions and visibility for GitHub Apps
GitHub Apps can be installed directly on organizations and personal accounts and granted access to specific repositories. They come with built-in webhooks and narrow, specific permissions. When you set up your GitHub App, you can select specific permissions for the app. These permissions determine what the app can do via the GitHub API, what they can do on behalf of a signed in user, and what webhooks the app can receive. When the app is then installed on a user or organization account, the person who installs the app decides what repositories the app can access under that account. For more information, see "Choosing permissions for a GitHub App."
By default, only organization owners can manage the settings of GitHub Apps in an organization. To allow additional users to change the developer settings of GitHub Apps owned by the organization, an owner can grant them GitHub App manager permissions. GitHub App Managers can't manage third-party applications. For more information about adding and removing GitHub App managers in your organization, see "Roles in an organization."
You can set the visibility of your app to control who can install it. You can make it public so that other GitHub users or organizations can install the app, or private so that you can only install it on the account that owns the app. For more information, see "Making a GitHub App public or private."
When to use GitHub Apps
When building an integration, you should consider using a GitHub App in the following scenarios instead of an OAuth App, personal access token, or GitHub Actions.
Using a GitHub App instead of an OAuth App
In general, GitHub Apps are preferred over OAuth Apps.
For more information, see "Differences between GitHub Apps and OAuth Apps."
For information on how to migrate an existing OAuth App to a GitHub App, see "Migrating OAuth Apps to GitHub Apps."
GitHub Apps offer enhanced security
GitHub Apps provide more control over what the app can do. Instead of the broad scopes that OAuth Apps use, GitHub Apps use fine-grained permissions. For example, if your app needs to read the contents of a repository, an OAuth App would require the repo scope, which would also let the app edit the repository contents and settings. A GitHub App can request read-only access to repository contents, which will not let the app take more privileged actions like editing the repository contents or settings.
GitHub Apps also offer more control over repository access. With a GitHub App, the user or organization owner who installed the app can decide what repositories the app can access. Conversely, an OAuth App can access every repository that the user who authorized the app can access.
GitHub Apps use short lived tokens. If the token is leaked, the token will be valid for a shorter amount of time, which reduces the damage that can be done. Conversely, OAuth App tokens do not expire until the person who authorized the OAuth App revokes the token.
These security features help harden your GitHub App's security by limiting the damage that could be done if your app's credentials were leaked. Additionally, this lets organizations with stricter security policies use your app.
GitHub Apps can act independently of or on behalf of a user
GitHub Apps can act independently of a user. This is beneficial for automations that do not require user input.
Similar to OAuth Apps, GitHub Apps can still take actions on behalf of a user. Unlike OAuth Apps, which don't indicate that the action was performed by the app, GitHub Apps indicate that the action was performed by the app on behalf of the user.
GitHub Apps are not tied to a user account and do not consume a seat on GitHub Enterprise Server. GitHub Apps remain installed even when the person who initially installed the app leaves the organization. This lets your integrations continue to work even if people leave your team.
GitHub Apps have scalable rate limits
The rate limit for GitHub Apps using an installation access token scales with the number of repositories and number of organization users. Conversely, OAuth Apps have lower rate limits and do not scale. For more information, see "Rate limits for GitHub Apps."
GitHub Apps have built in webhooks
GitHub Apps have built-in, centralized webhooks. GitHub Apps can receive webhook events for all repositories and organizations the app can access. Conversely, OAuth Apps must configure webhooks individually for each repository and organization.
API access differs slightly
In general, GitHub Apps and OAuth Apps can make the same API requests. However, there are some differences:
- The REST API to manage check runs and check suites is only available to GitHub Apps.
- Enterprise resources are only available to OAuth Apps.
- Some requests may return incomplete data depending on the permissions and repository access that was granted to an GitHub App. For example, if your app makes a request to get all repositories that a user can access, the response will only include the repositories that the app was also granted access to.
For more information about the REST API endpoints that are available to GitHub Apps, see "Endpoints available for GitHub Apps."
Choosing between a GitHub App or a personal access token
If you want to access GitHub resources on behalf of a user or in an organization, or you anticipate a long-lived integration, we recommend building a GitHub App.
You can use personal access tokens for API testing or short-lived scripts. Since a personal access token is associated with a user, your automation could break if the user no longer has access to the resources you need. A GitHub App installed in an organization is not dependent on a user. Additionally, unlike a user, a GitHub App does not consume a GitHub seat.
GitHub supports two types of personal access tokens, but recommends that you use fine-grained personal access tokens instead of personal access tokens whenever possible. For more information about personal access tokens, see "Creating a personal access token."
Choosing between a GitHub App or GitHub Actions
GitHub Apps and GitHub Actions both provide ways to build automation and workflow tools.
GitHub Actions provide automation that can perform jobs like continuous integration, deployment tasks, and project management in a repository. They run directly on GitHub-hosted runner machines or self-hosted runners that your administrator sets up. GitHub Actions do not run persistently. They run in response to events that occur in their repository, and only have access to the resources of the repository that they are set up for. However, they can be shared across repositories and organizations, allowing developers to reuse and modify existing actions to meet their needs. GitHub Actions also come with built-in secret management, which you can use to securely interact with third-party services and manage deploy keys safely.
GitHub Apps run persistently on a server or compute infrastructure that you provide, and they react to webhook events as well as events from outside the GitHub ecosystem. They are a good option for operations that span multiple repositories or organizations, or for providing hosted services to other organizations. A GitHub App is the best choice when building a tool with functions that occur primarily outside of GitHub or require more time than what an action is allotted for execution.
For more information about comparing GitHub Actions to GitHub Apps, see "About custom actions."
You can use a GitHub App to authenticate in a GitHub Actions
workflow if the built in GITHUB_TOKEN does not have sufficient permissions. For more information, see "Making authenticated API requests with a GitHub App in a GitHub Actions workflow."
Understanding what type of GitHub App to build
There are multiple ways to design a GitHub App that you will want to consider, based on the functionality you want the app to have.
GitHub Apps that act on behalf of a user
If you want your app to take actions on behalf of a user, you should use a user access token for authentication. This type of request is sometimes called "user-to-server," and it means that the app will be limited by the permissions that have been given to the app as well as the user's permission. With this pattern, the user must authorize the app before the app can take action. For more information, see "Authenticating with a GitHub App on behalf of a user."
Some examples of automations you could create with a GitHub App, where the app acts on a user's behalf, include:
- A GitHub App that uses GitHub as an identity provider for your ecosystem
- A GitHub App that adds a service on top of GitHub.com that might be useful to a GitHub user. You can share the app with other developers via GitHub Marketplace or by making the app public
GitHub Apps that act on their own behalf
If you want your app to take actions on behalf of itself, rather than a user, you should use an installation access token for authentication. This type of request is sometimes called "server-to-server," and it means that the app will be limited by the permissions that have been given to the app. For more information, see "Authenticating as a GitHub App installation."
Some examples of automations you could create with a GitHub App, where the app acts on its own behalf, include:
- A GitHub App that uses webhooks to react to an event given a certain set of criteria. For example, you could create an automation that uses the REST API endpoints for labels to add a label to each new issue created in a repository, given a certain set of criteria
- A GitHub App that helps repository contributors. For example, the app could post helpful resources after a contributor creates a pull request or makes a comment
- A GitHub App that generates short-lived tokens to give to other CI/CD tools, or to pull information from a repository