GitHub Apps について
GitHub App は、GitHub の機能を操作して拡張するために構築できる統合の一種です。 GitHub App を構築して、ユーザーのサインインやサービス アカウントの作成を必要とせずに、柔軟性を提供し、プロセスの摩擦を軽減できます。
GitHub Apps の一般的なユース ケースは次のとおりです。
- タスクまたはバックグラウンド プロセスの自動化
- "GitHub によるサインイン" のサポート。これにより、ユーザーは、自分の GitHub アカウントでサインインし、エコシステムで ID を提供できます
- 開発ツールとしての使用。これにより、ユーザーは、GitHub App にサインインして GitHub を操作できるようになります。その後、アプリはユーザーに代わって動作できます
- ツールまたは外部サービスと GitHub の統合
OAuth apps と同様に、GitHub Apps でも OAuth 2.0 が使われ、ユーザーの代わりに動作することができます。 OAuth apps とは異なり、GitHub Apps はユーザーから独立して動作することもできます。
GitHub Apps は、組織や個人アカウントに直接インストールでき、特定のリポジトリへのアクセス権を付与できます。 精細なアクセス権限が付いており、webhook が組み込まれています。
デフォルトでは、Organization内のGitHub Appsの設定を管理できるのはOrganizationのオーナーだけです。 組織が所有する GitHub Apps の開発者設定を追加ユーザーが変更できるようにするため、所有者は GitHub App マネージャーのアクセス許可を付与できます。 GitHub App マネージャーは、サード パーティのアプリケーションを管理できません。 組織での GitHub App マネージャーの追加と削除の詳細については、「Organizationのロール」を参照してください。
GitHub App の作成
GitHub App を作成するには、まず GitHub App を登録する必要があります。 詳しくは、「GitHub App の登録」を参照してください。
次に、コードを記述して GitHub App に機能を追加する必要があります。 GitHub App 登録の資格情報を使って、GitHub の API に対して認証された要求を行うことができます。 GitHub App のコードを記述する方法について詳しくは、「GitHub App のコードの記述について」を参照してください。 認証された要求を行う方法について詳しくは、「GitHub アプリでの認証について」を参照してください。
GitHub App のコードを記述したら、アプリをどこかで実行する必要があります。 アプリが Web サイトまたは Web アプリの場合は、Azure App Service などのサーバー上でアプリをホストできます。 アプリがクライアント側アプリの場合は、ユーザーのデバイス上で実行できます。
GitHub App を使うには、組織または個人用アカウントにアプリをインストールする必要があります。 GitHub App が非公開の場合、アプリを所有するアカウントでのみ GitHub App をインストールできます。 GitHub App がパブリックの場合は、他のユーザーや組織がアプリをインストールできます。 詳細については、「独自の GitHub App のインストール」および「GitHub App の共有」を参照してください。
構築する GitHub App の種類について
GitHub App を設計する方法は複数あり、アプリに必要な機能に基づいてそれらを検討する必要があります。
ユーザーに代わって実行する GitHub Apps
アプリでユーザーに代わってアクションを実行する場合は、認証にユーザー アクセス トークンを使用する必要があります。 この種類の要求は "user-to-server" と呼ばれることがあり、アプリに付与されたアクセス許可とユーザーのアクセス許可によってアプリが制限されることを意味します。 このパターンでは、アプリでアクションが実行される前に、ユーザーがアプリを承認する必要があります。 詳しくは、「ユーザーに代わって GitHub アプリで認証する」を参照してください。
GitHub App を使用して作成できる自動化 (ユーザーに代わってアプリが実行する場合) の例としては、次のようなものがあります。
- エコシステムの ID プロバイダーとして GitHub を使用する GitHub App。
- GitHub ユーザーに役立つ可能性があるサービスを GitHub.com の上に追加する GitHub App。 GitHub Marketplace を通じて、またはアプリを公開することで、他の開発者とアプリを共有できます。
独自で実行する GitHub Apps
アプリがユーザーの代わりではなく独自で実行する場合、認証にインストール アクセス トークンを使用する必要があります。 この種類の要求は、"server-to-server" とも呼ばれることがあり、アプリに付与されたアクセス許可によってアプリが制限されることを意味します。 詳しくは、「GitHub App インストールとしての認証」を参照してください。
GitHub App を使用して作成できる自動化 (アプリが独自で実行する場合) の例としては、次のようなものがあります。
- 特定の基準セットがある場合に Webhook を使用してイベントに対応する GitHub App。 たとえば、特定の基準セットがある場合に、ラベル用の REST API エンドポイントを使用する自動化を作成して、リポジトリで作成された新しいイシューごとにラベルを追加できます。
- リポジトリの共同作成者に役立つ GitHub App。 たとえば、共同作成者が pull request を作成した後またはコメントを作成した後、アプリで有用なリソースを投稿できます。
- 他の CI/CD ツールに提供するため、またはリポジトリから情報をプルするために、有効期間の短いトークンを生成する GitHub App。
Webhook に応答する GitHub Apps
アプリで GitHub のイベントに応答する必要がある場合、アプリで Webhook をサブスクライブする必要があります。 たとえば、pull request が開かれたときにアプリにコメントを残すことができます。 詳しくは、「GitHub Apps での Webhook の使用」を参照してください。
特定のアクションを実行できる GitHub Apps
GitHub App を設定する際、アプリの特定のアクセス許可を選択できます。 これらのアクセス許可によって、アプリで GitHub API を使用して実行できること、サインインしたユーザーに代わって実行できること、アプリで受け取ることができる Webhook が決定されます。 詳しくは、「GitHub アプリのアクセス許可を選択する」を参照してください。