GitHub App の作成について

GitHub Apps について

GitHub App は、GitHub の機能を操作して拡張するために構築できる統合の一種です。 GitHub App を構築して、ユーザーのサインインやサービスアカウントの作成を必要とせずに、柔軟性を提供し、プロセスの摩擦を軽減できます。

GitHub Apps の一般的なユースケースは次のとおりです。

タスクまたはバックグラウンドプロセスの自動化
"GitHub によるサインイン" のサポート。これにより、ユーザーは、自分の GitHub アカウントでサインインし、エコシステムで ID を提供できます
開発ツールとしての使用。これにより、ユーザーは、GitHub App にサインインして GitHub を操作できるようになります。その後、アプリはユーザーに代わって動作できます
ツールまたは外部サービスと GitHub の統合

GitHub Apps は、GitHub 内の独立したアクターです。 GitHub App は独自で動作します。つまり、ボットまたはサービスアカウントを別のユーザーとして維持する必要はありません。また、ユーザーとして認証し、ユーザーに付与されたアクセス許可を使用してユーザーの代わりに動作することもできます。

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

開発中、開発のためにアプリをローカルで実行できます。アプリを運用環境で使用する準備ができたら、アプリを専用サーバーにデプロイする必要があります。たとえば、Azure App Service を使用できます。

GitHub Apps のアクセス許可と可視性

GitHub Apps は、Organization や個人アカウントに直接インストールでき、特定のリポジトリへのアクセス権を付与できます。精細なアクセス権限が付いており、webhook が組み込まれています。 GitHub App を設定する際、アプリの特定のアクセス許可を選択できます。これらのアクセス許可によって、アプリで GitHub API を使用して実行できること、サインインしたユーザーに代わって実行できること、アプリで受け取ることができる Webhook が決定されます。その後、アプリがユーザーまたは Organization アカウントにインストールされると、アプリをインストールするユーザーが、アプリがそのアカウントでアクセスできるリポジトリを決定します。詳しくは、「GitHub アプリのアクセス許可を選択する」を参照してください。

デフォルトでは、Organization内のGitHub Appsの設定を管理できるのはOrganizationのオーナーだけです。組織が所有する GitHub Apps の開発者設定を追加ユーザーが変更できるようにするため、所有者は GitHub App マネージャーのアクセス許可を付与できます。 GitHub App マネージャーは、サードパーティのアプリケーションを管理できません。組織での GitHub App マネージャーの追加と削除の詳細については、「Organizationのロール」を参照してください。

アプリの可視性を設定して、アプリをインストールできるユーザーを制御できます。他の GitHub ユーザーまたは Organization がインストールできるようにアプリを公開するか、アプリを所有するアカウントにのみインストールできるように非公開にすることができます。詳しくは、「GitHub Appをパブリックまたはプライベートにする」を参照してください。

GitHub Apps を使用する場合

統合を構築する際、次のシナリオで OAuth App、personal access token、または GitHub Actions の代わりに GitHub App を使用することを検討する必要があります。

OAuth App の代わりに GitHub App を使用する

通常、GitHub App は OAuth App よりも優先されます。

詳しくは、「GitHub アプリと OAuth アプリとの微妙な違い」を参照してください。

既存の OAuth App を GitHub App に移行する方法については、「OAuth AppからGitHub Appへの移行」を参照してください。

GitHub App で強化されたセキュリティを提供する

GitHub App を使用すると、アプリで実行できることをより細かく制御できます。 GitHub App では、OAuth App で使用される広範なスコープの代わりに、きめ細かいアクセス許可を使用します。たとえば、アプリでリポジトリのコンテンツを読み取る必要がある場合、OAuth App には repo スコープが必要です。これにより、アプリでリポジトリのコンテンツと設定を編集することもできます。 GitHub App では、リポジトリのコンテンツに対する読み取り専用アクセスを要求できます。これにより、アプリでは、リポジトリのコンテンツまたは設定の編集など、より高い特権のアクションを実行できなくなります。

GitHub App では、リポジトリへのアクセスもより細かく制御できます。 GitHub App を使用すると、アプリをインストールしたユーザーまたは Organization 所有者は、アプリでアクセスできるリポジトリを決定できます。現在、OAuth App では、アプリを承認したユーザーがアクセスできるすべてのリポジトリにアクセスできます。

GitHub App では、有効期間が短いトークンが使用されます。トークンが漏洩した場合、トークンの有効期間は短くなり、発生する可能性のある損害が軽減されます。逆に、OAuth App を承認したユーザーが OAuth App トークンを取り消すまで、トークンは期限切れになりません。

これらのセキュリティ機能は、アプリの資格情報が漏洩した場合に発生する可能性のある損害を制限することで、GitHub Appのセキュリティを強化するのに役立ちます。さらに、これにより、より厳格なセキュリティポリシーを持つ Organization がアプリを使用できるようになります。

GitHub App は、ユーザーとは関係なく、またはユーザーに代わって動作できる

GitHub App は、ユーザーとは関係なく動作できます。これは、ユーザー入力を必要としない自動化に役立ちます。

OAuth App と同様に、GitHub App でもユーザーに代わってアクションを実行できます。アクションがアプリによって実行されたことを示さない OAuth App とは異なり、GitHub App では、ユーザーに代わってアプリによりアクションが実行されたことを示します。

GitHub App はユーザーアカウントに関連付けられず、GitHub Enterprise Server のシートを使用しません。 GitHub App は、アプリを最初にインストールしたユーザーが Organization を離れても、インストールされたままになります。これにより、ユーザーが Team を離れた場合でも、統合は引き続き機能します。

GitHub App にはスケーラブルなレート制限がある

インストールアクセストークンを使用する GitHub App のレート制限は、リポジトリの数と Organization ユーザーの数に応じてスケーリングされます。逆に、OAuth Apps のレート制限は低く、スケーリングされません。詳しくは、「Rate limits for GitHub Apps」を参照してください。

GitHub App には Webhook が組み込まれている

GitHub App には、一元化された Webhook が組み込まれています。 GitHub App は、アプリでアクセスできるすべてのリポジトリおよび Organization の Webhook イベントを受け取ることができます。逆に、OAuth App では、リポジトリおよび Organization ごとに個別に Webhook を構成する必要があります。

API アクセスが多少異なる

通常、GitHub App と OAuth App は同じ API 要求を行うことができます。ただし、いくつかの違いがあります。

チェック実行とチェックスイートを管理する REST API は、GitHub App でのみ使用できます。
エンタープライズリソースは、OAuth App でのみ使用できます。
GitHub App に付与されたアクセス許可とリポジトリへのアクセスによっては、一部の要求で不完全なデータが返される場合があります。たとえば、アプリで、ユーザーがアクセスできるすべてのリポジトリを取得するように要求した場合、応答には、アプリがアクセスを許可されたリポジトリのみが含まれます。

GitHub App で使用できる REST API エンドポイントについて詳しくは、「GitHub App で利用可能なエンドポイント」を参照してください。

GitHub App または personal access token のいずれかを選択する

ユーザーに代わってまたは Organization で、GitHub リソースにアクセスする場合、または統合が長期にわたることが予想される場合は、GitHub App を構築することをお勧めします。

personal access tokens は、API のテストまたは有効期間の短いスクリプトに使用できます。 personal access token はユーザーに関連付けられているため、必要なリソースにアクセスできなくなると、自動化が機能しなくなる可能性があります。 Organization にインストールされる GitHub App は、ユーザーに依存しません。さらに、ユーザーとは異なり、GitHub App は GitHub シートを使用しません。

GitHub では、2 種類の personal access tokens がサポートされていますが、可能な限り、personal access tokens ではなく fine-grained personal access token を使用することをお勧めします。 personal access tokens について詳しくは、「個人用アクセストークンの作成」を参照してください。

GitHub App または GitHub Actions のいずれかを選択する

GitHub Apps と GitHub Actions は両方とも、自動化とワークフローのツールを構築する方法を提供します。

GitHub Actions では、リポジトリで継続的インテグレーション、デプロイタスク、プロジェクト管理などのジョブを実行できる自動化が提供されます。これらは、管理者が設定した、GitHub でホストされるランナーマシンまたはセルフホステッドランナーで直接実行されます。 GitHub Actions は永続的に実行されません。これらは、リポジトリで発生するイベントに応答して実行され、そのジョブ用に設定されたリポジトリのリソースにのみアクセスできます。ただし、これらをリポジトリや Organization 間で共有できるため、開発者はニーズに合わせて既存のアクションを再利用および変更できます。 GitHub Actions には組み込みのシークレット管理も付属しており、これを使用してサードパーティサービスと安全にやり取りしたり、デプロイキーを安全に管理したりすることができます。

GitHub Apps は、提供されたサーバーまたはコンピューティングインフラストラクチャ上で永続的に実行され、GitHub エコシステムの外部からのイベントだけでなく、Webhook イベントにも対応します。これらは、複数のリポジトリまたは Organization にまたがる操作や、ホストされたサービスを他の Organization に提供する場合に適したオプションです。 GitHub App は、主に GitHub の外部で発生する機能や、実行に割り当てられたアクションよりも多くの時間を必要とする機能を含むツールを構築する場合に最適です。

GitHub Actions と GitHub Apps の比較について詳しくは、「カスタムアクションについて」を参照してください。

組み込みの GITHUB_TOKEN に十分なアクセス許可がない場合、GitHub Actions ワークフローで GitHub App を使用して認証できます。詳しくは、「GitHub Actions ワークフローで GitHub App を使用して認証済み API 要求を作成する」を参照してください。

構築する 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