GitHub App の作成について

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 は、Enterprise、organization、個人用アカウントに直接インストールし、特定のリポジトリへのアクセス権を付与できます。 精細なアクセス権限が付いており、webhook が組み込まれています。

また、Enterprise 所有の GitHub App を作成することもできます。これは、Enterprise または Enterprise 内の organization にのみインストールできます。また、Enterprise のメンバーのみが認可できます。 詳しくは、「Enterprise 向け GitHub Apps の作成」をご覧ください。

デフォルトでは、Organization内のGitHub Appsの設定を管理できるのはOrganizationのオーナーだけです。 組織が所有する GitHub Apps の開発者設定を追加ユーザーが変更できるようにするため、所有者は GitHub App マネージャーのアクセス許可を付与できます。 GitHub App マネージャーは、サード パーティのアプリケーションを管理できません。 Organization での 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 を使うには、Enterprise、organization、または個人用アカウントにインストールする必要があります。

• GitHub App がプライベートの場合は、アプリを所有するアカウントでのみインストールできます。
• GitHub App が公開されている場合、他のアカウントもインストールできます。
• GitHub App が Enterprise によって所有されている場合は、その Enterprise またはその Enterprise 内の任意の organization にインストールできます。サインインできるのは、その Enterprise のメンバーのみです。

詳細については、「独自の GitHub App のインストール」および「GitHub App の共有」を参照してください。

構築する GitHub App の種類について

GitHub App を設計する方法は複数あり、アプリに必要な機能に基づいてそれらを検討する必要があります。

ユーザーに代わって実行する GitHub Apps

アプリでユーザーに代わってアクションを実行する場合は、認証にユーザー アクセス トークンを使用する必要があります。 この種類の要求は "user-to-server" と呼ばれることがあり、アプリに付与されたアクセス許可とユーザーのアクセス許可によってアプリが制限されることを意味します。 このパターンでは、アプリでアクションが実行される前に、ユーザーがアプリを承認する必要があります。 詳しくは、「ユーザーに代わって GitHub アプリで認証する」をご覧ください。

GitHub App を使用して作成できる自動化 (ユーザーに代わってアプリが実行する場合) の例としては、次のようなものがあります。

• エコシステムの ID プロバイダーとして GitHub を使用する GitHub App。
• GitHub ユーザーに役立つ可能性があるサービスを GitHub の上に追加する GitHub App。 GitHub Marketplace を通じて、またはアプリを公開することで、他の開発者とアプリを共有できます。

独自で実行する GitHub Apps

アプリがユーザーの代わりではなく独自で実行する場合、認証にインストール アクセス トークンを使用する必要があります。 この種類の要求は、"server-to-server" とも呼ばれることがあり、アプリに付与されたアクセス許可によってアプリが制限されることを意味します。 詳しくは、「GitHub App インストールとしての認証」をご覧ください。

GitHub App を使用して作成できる自動化 (アプリが独自で実行する場合) の例としては、次のようなものがあります。

• 特定の基準セットがある場合に Webhook を使用してイベントに対応する GitHub App。 たとえば、fine-grained personal access token に対する要求を確認するために、REST API エンドポイントを中心に特定のポリシーが与えられた要求を承認する自動化を作成できます。
• リポジトリの共同作成者に役立つ GitHub App。 たとえば、共同作成者が pull request を作成した後またはコメントを作成した後、アプリで有用なリソースを投稿できます。
• 他の CI/CD ツールに提供するため、またはリポジトリから情報をプルするために、有効期間の短いトークンを生成する GitHub App。

Webhook に応答する GitHub Apps

アプリで GitHub のイベントに応答する必要がある場合、アプリで Webhook をサブスクライブする必要があります。 たとえば、pull request が開かれたときにアプリにコメントを残すことができます。 詳しくは、「GitHub Apps での Webhook の使用」をご覧ください。

現在、Enterprise にインストールされたアプリは Webhook をサポートしていないため、Webhook を受信するには organization にインストールする必要があります。

特定のアクションを実行できる GitHub Apps

GitHub App を設定する際、アプリの特定のアクセス許可を選択できます。 これらのアクセス許可によって、アプリで GitHub API を使用して実行できること、サインインしたユーザーに代わって実行できること、アプリで受け取ることができる Webhook が決定されます。 詳しくは、「GitHub アプリのアクセス許可を選択する」をご覧ください。