OAuth apps から GitHub Apps への移行のメリット
GitHub Apps は、 GitHubと統合するための推奨される方法です。 GitHub Apps OAuth appsよりも多くの利点があります。
- きめ細かいアクセス許可、リポジトリ アクセスの選択肢、有効期間の短いトークンなどの強化されたセキュリティ機能
- ユーザーから独立して、またはユーザーに代わって動作できること
- スケーラブルなレート制限
- 組み込みの Webhook 機能
詳しくは、「GitHub アプリの作成について」をご覧ください。
OAuth appを a に変換するGitHub App
次の手順では、 OAuth app から GitHub Appに移行する方法の概要を示します。 具体的な手順は、アプリによって異なります。
1. ご自身のOAuth appを確認してください
OAuth appのコードを理解し直してください。 OAuth appが行う API 要求は、GitHub Appに対して選択するアクセス許可を決定するのに役立ちます。
さらに、 OAuth appsで使用できない REST API エンドポイントがいくつかあります。 GitHub Apps を確認して、使用するすべての REST エンドポイントがで使用可能であることを確認します。
2. GitHub App を登録します
新しい GitHub Appを登録します。 詳しくは、「GitHub アプリの登録」をご覧ください。
OAuth appと比較して、GitHub App設定をより詳細に制御できます。 いくつかの重要な追加は次のとおりです。
-
常にユーザーの代わりに機能する OAuth appとは異なり、 GitHub App 自身またはユーザーの代わりにアクションを実行できます。 新しい GitHub App がユーザーに代わってアクションを実行しないようにする場合は、[ユーザーの識別と承認] 設定をスキップできます。 詳しくは、「GitHub アプリでの認証について」をご覧ください。
-
Webhook を使用して、特定のイベントが発生したときに GitHub App に通知できます。 各リポジトリまたは組織の API を使用して構成する必要がある OAuth appsの webhook とは異なり、webhook は GitHub Appsに組み込まれています。 GitHub Appを登録するときに、受信する Webhook イベントを選択できます。 さらに、 OAuth app が現在ポーリングを使用してイベントが発生したかどうかを判断する場合は、代わりに webhook をサブスクライブして、 GitHub App がレート制限内に収まるようにすることを検討してください。 詳しくは、「GitHub Apps での Webhook の使用」をご覧ください。
-
OAuth appでは、ユーザーがアプリを承認するときにスコープを要求します。 GitHub Appでは、アプリ設定でアクセス許可を指定します。 これらのアクセス許可はスコープよりも細かく、アプリに必要なアクセス許可のみを選ぶことができます。 さらに、これらのアクセス許可は REST API エンドポイントと webhook イベントにマップされるため、特定の REST API エンドポイントにアクセスしたり、特定の Webhook をサブスクライブしたりするために GitHub App に必要なアクセス許可を簡単に決定できます。 現在、GraphQL 要求に関するアクセス許可は文書化されていません。 詳しくは、「GitHub アプリのアクセス許可の選択」をご覧ください。
3. アプリのコードを変更する
GitHub Appを登録したら、古いOAuth appのコードを新しいGitHub Appで動作するように調整します。
認証を更新する
GitHub Appの API 認証を処理するには、アプリのコードを更新する必要があります。 GitHub Appは、次の 3 つの方法で認証できます。
- アプリ自体として、 GitHub App 登録に関する詳細を取得または変更したり、インストール アクセス トークンを作成したりするため。 詳しくは、「GitHub アプリとしての認証」をご覧ください。
- アプリ自体の代理としてアクションを実行するために、アプリのインストールとして。 詳しくは、「GitHub App インストールとしての認証」をご覧ください。
- ユーザーの代理として、アクションをユーザーに帰属させるために。 詳しくは、「ユーザーに代わってGitHub アプリで認証する」をご覧ください。
GitHubの公式 Octokit.js ライブラリを使用している場合は、組み込みのApp オブジェクトを使用して認証できます。 例については、「REST API と JavaScript を使用したスクリプト」と「webhook イベントに応答するGitHub アプリの構築」を参照してください。
レート制限を確認する
OAuth appsとGitHub Appsのレート制限の違いを確認します。 GitHub Apps では、レート制限にスライディング ルールを使用します。これは、組織内のリポジトリの数とユーザー数に基づいて増加する可能性があります。 詳しくは、「GitHub アプリのレート制限」をご覧ください。
可能であれば、条件付きの要求を使用し、ポーリングではなく Webhook へのサブスクライブによってレート制限内に留まるようにすることを検討してください。 条件付きの要求の詳細については、「REST API を使用するためのベスト プラクティス」を参照してください。 GitHub Appでの Webhook の使用の詳細については、GitHub Apps での Webhook の使用 と webhook イベントに応答するGitHub アプリの構築 に関するページを参照してください。
コードをテストする
新しい GitHub App をテストして、コードが期待どおりに動作することを確認します。
4. 新しいGitHub Appを告知する
他のアカウントで新しい GitHub Appを使用できるようにする場合は、アプリがパブリックであることを確認します。 GitHub Appを見つけやすくするには、GitHub Marketplaceでアプリを一覧表示します。 詳細については、「 GitHub Marketplace for apps について と GitHub アプリをパブリックまたはプライベートにする」を参照してください。
5. ユーザーに移行を指示する
新しい GitHub App の準備ができたら、古い OAuth app のユーザーに新しい GitHub Appに移行するように指示します。 ユーザーを自動的に移行する方法はありません。 各ユーザーは、自分で GitHub App をインストールまたは承認する必要があります。
アプリの所有者は、ユーザーが新しい GitHub App をインストールまたは承認し、古い OAuth appの承認を取り消すように促す行動の呼び出しを含める必要があります。 ドキュメントまたはユーザー インターフェイス要素も更新する必要があります。
ユーザーにGitHub Appのインストールを促す
GitHub Appが自身の代わりに API 要求を行うか、組織またはリポジトリのリソースにアクセスする場合は、ユーザーがGitHub Appをインストールする必要があります。 ユーザーが自分のアカウントまたは組織に GitHub App をインストールすると、アプリがアクセスできるリポジトリを選択し、要求した組織とリポジトリのアクセス許可をアプリに付与します。
ユーザーが GitHub Appをインストールできるように、ユーザーがクリックして GitHub Appをインストールできるアプリの Web ページへのリンクを追加できます。 インストール URL の形式は https://github.com/apps/YOUR_APP_NAME/installations/new です。
YOUR_APP_NAME を、GitHub App のスラッグ化された名前に置き換えてください。この名前は、GitHub App の設定ページにある［Public link］フィールドで確認できます。
OAuth appがアクセスできるリポジトリを事前に選択するには、/permissionsとクエリ パラメーターをインストール URL に追加します。 これにより、ユーザーは、GitHub Appが既にアクセスできるリポジトリへのOAuth appアクセス権を付与できます。 クエリ パラメーターは次のとおりです。
suggested_target_id: GitHub Appをインストールしているユーザーまたは組織の ID。 このパラメーターは必須です。repository_ids[]: インストール用に選ぶリポジトリ ID。 省略すると、すべてのリポジトリが選ばれます。 事前選択できるリポジトリ数は、最大で100です。 OAuth appがアクセスできるリポジトリの一覧を取得するには、認証済みユーザーのリスト リポジトリと List 組織リポジトリ エンドポイントを使用します。
たとえば、 https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_IDと指定します。
GitHub Appsのインストールの詳細については、「個人向けアカウント用に GitHub Marketplace から GitHub アプリをインストールする、Organization の GitHub Marketplace から GitHub アプリをインストールする、サードパーティ製 GitHub App のインストール、独自のGitHub アプリのインストール」を参照してください。
アプリの承認をユーザーに求める
GitHub Appがユーザーに代わって API 要求を行う場合、ユーザーはアプリを承認する必要があります。 ユーザーは、アプリを承認するときに、ユーザーの代わりに動作するためのアクセス許可をアプリに付与し、アプリから要求されたアカウント アクセス許可を付与します。 アプリが Organization アカウントにインストールされている場合、その Organization 内の各ユーザーは、アプリが自分の代わりに動作できるようにアプリを承認する必要があります。
ユーザーにアプリの承認を求めるために、Web アプリケーション フローまたはデバイス フローを介してユーザーを誘導します。 詳しくは、「GitHub アプリのユーザー アクセス トークンの生成」をご覧ください。
GitHub Appsの承認の詳細については、GitHub アプリの承認 を参照してください。
OAuth appアクセスを取り消すようユーザーに促す
また、古い OAuth appのアクセス権を取り消すようユーザーに勧める必要があります。 これは、 OAuth app から完全に移行するのに役立ち、ユーザーのデータのセキュリティを維持するのに役立ちます。 詳しくは、「承認された OAuth アプリをレビューする」をご覧ください。
インターフェイスまたはドキュメントを更新する
OAuth appからGitHub Appへの変更を反映するように、アプリに関連するユーザー インターフェイスまたはドキュメントを更新する必要があります。
6. 古い OAuth app の webhook を削除する
ユーザーが GitHub App をインストールし、リポジトリへのアクセスを許可する場合は、古い OAuth appの Webhook をすべて削除する必要があります。 新しい GitHub App と古い OAuth app が同じイベントの Webhook に応答すると、ユーザーは重複する動作を観察する可能性があります。
リポジトリの Webhook を削除するには、installation_repositories アクションを使用して added Webhook を監視できます。
GitHub Appがそのイベントを受け取ったら、REST API を使用して、OAuth appのこれらのリポジトリの Webhook を削除できます。 詳細については、「Webhook のイベントとペイロード」および「リポジトリ ウェブフック の REST API エンドポイント」を参照してください。
同様に、Organization の Webhook を削除するには、installation アクションを使用して created Webhook をリッスンできます。
GitHub Appが組織のイベントを受け取ったら、REST API を使用して、その組織の Webhook とOAuth appの対応するリポジトリを削除できます。 詳細については、「Webhook のイベントとペイロード」、「組織の Webhook の REST API エンドポイント」、「リポジトリ ウェブフック の REST API エンドポイント」を参照してください。
7. 古いファイルを削除する OAuth app
ユーザーが新しい GitHub Appに移行したら、古い OAuth appを削除する必要があります。 これにより、 OAuth appの資格情報の不正使用を回避できます。 このアクションでは、 OAuth appの残りの承認もすべて取り消されます。 詳しくは、「OAuth アプリの削除」をご覧ください。 OAuth appにGitHub Marketplaceが表示されている場合は、まずGitHub のサポートに連絡して、マーケットプレースからアプリを削除する必要があります。