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
Like OAuth Apps, GitHub Apps use OAuth 2.0 and can act on behalf of a user. Unlike OAuth Apps, GitHub Apps can also act independently of a user.
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.
デフォルトでは、Organization内のGitHub Appsの設定を管理できるのはOrganizationのオーナーだけです。 組織が所有する GitHub Apps の開発者設定を追加ユーザーが変更できるようにするため、所有者は GitHub App マネージャーのアクセス許可を付与できます。 GitHub App マネージャーは、サード パーティのアプリケーションを管理できません。 組織での GitHub App マネージャーの追加と削除の詳細については、「Organizationのロール」を参照してください。
Building a GitHub App
In order to build a GitHub App, you first need to register a GitHub App. For more information, see "Registering a GitHub App."
Then, you need to write code to add functionality to your GitHub App. You can use the credentials from your GitHub App registration to make authenticated requests to GitHub's APIs. For more information about writing code for your GitHub App, see "About writing code for a GitHub App." For more information about making authenticated requests, see "GitHub アプリでの認証について."
Once you have written the code for your GitHub App, your app needs to run somewhere. If your app is a website or web app, you might host your app on a server like Azure App Service. If your app is a client-side app, it might run on a user's device.
In order to use your GitHub App, you must install the app on your organization or personal account. If your GitHub App is private, your can only install the GitHub App on the account that owns the app. If your GitHub App is public, other users and organizations can install your app. For more information, see "独自の GitHub App のインストール" and "GitHub App の共有."
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 "ユーザーに代わって GitHub アプリで認証する."
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 "GitHub App インストールとしての認証."
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.
GitHub Apps that respond to webhooks
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."
GitHub Apps that can take certain actions
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. For more information, see "Choosing permissions for a GitHub App."