OAuth アプリからGitHub Appへの移行

OAuth apps から GitHub Apps に移行する利点

GitHub Apps は、GitHub との統合方法として推奨されています。 GitHub Apps には、OAuth apps に比べて多くの利点があります。

• きめ細かいアクセス許可、リポジトリ アクセスの選択肢、有効期間の短いトークンなどの強化されたセキュリティ機能
• ユーザーから独立して、またはユーザーに代わって動作できること
• スケーラブルなレート制限
• 組み込みの Webhook

詳しくは、「GitHub App の作成について」をご覧ください。

OAuth app から GitHub App への切り替え

次の手順では、OAuth app から GitHub App に移行する方法の概要を示します。 具体的な手順は、アプリによって異なります。

1. OAuth app を確認する

OAuth app のコードを確認し直してください。 OAuth app が行う API 要求は、GitHub App に対して選ぶアクセス許可を決定するのに役立ちます。

さらに、OAuth apps では使用できない REST API エンドポイントがいくつかあります。 「GitHub App インストール アクセス トークンで使用できるエンドポイント」を参照して、使用する REST エンドポイントが GitHub Apps で使用可能であることを確認します。

2. GitHub App を登録する

新しい GitHub App を登録します。 詳しくは、「GitHub App の登録」をご覧ください。

OAuth app と比較すると、GitHub App の設定はより細かく制御できます。 いくつかの重要な追加は次のとおりです。

• 常にユーザーの代理として動作する OAuth app とは異なり、GitHub App は、それ自体として、またはユーザーの代理としてアクションを実行するように設定できます。 新しい GitHub App でユーザーの代理としてのアクションを実行しない場合は、"ユーザーの識別と承認" に関する設定をスキップできます。 詳しくは、「GitHub アプリでの認証について」をご覧ください。

• Webhook を使用すると、特定のイベントが発生したときに GitHub App に通知できます。 リポジトリまたは組織ごとに API を使って構成する必要がある OAuth apps の Webhook とは異なり、GitHub Apps には Webhook が組み込まれています。 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 Appとしての認証」をご覧ください。
• アプリ自体の代理としてアクションを実行するために、アプリのインストールとして。 詳しくは、「GitHub App インストールとしての認証」をご覧ください。
• アクションが帰属するユーザーを示すために、ユーザーの代理として。 詳しくは、「ユーザーに代わって GitHub アプリで認証する」をご覧ください。

GitHub の公式な Octokit.js ライブラリを使用している場合は、組み込みの App オブジェクトを使用して認証できます。 例については、「REST API と JavaScript を使用したスクリプト」と「Webhook イベントに応答する GitHub App の構築」を参照してください。

レート制限を確認する

GitHub Apps と OAuth apps のレート制限の違いを確認します。 GitHub Apps ではレート制限に対してスライディング ルールを使います。これは組織のリポジトリ数とユーザー数に基づいて増やすことができます。 詳しくは、「Rate limits for GitHub Apps (GitHub アプリのレート制限)」をご覧ください。

可能であれば、条件付きの要求を使用し、ポーリングではなく Webhook へのサブスクライブによってレート制限内に留まるようにすることを検討してください。 条件付きの要求の詳細については、「REST API を使用するためのベスト プラクティス」を参照してください。 GitHub App での Webhook の使用の詳細については、「GitHub Apps での Webhook の使用」と「Webhook イベントに応答する GitHub App の構築」を参照してください。

コードをテストする

新しい GitHub App をテストして、コードが想定どおりに動作することを確認します。

4. 新しい GitHub App を公開する

他のアカウントで新しい GitHub App を使用できるようにする場合は、アプリがパブリックであることを確認します。GitHub App を見つけやすくするには、アプリを GitHub Marketplace に掲載します。 詳細については、「アプリの GitHub Marketplace について」と「GitHub Appをパブリックまたはプライベートにする」を参照してください。

5. ユーザーに移行を指示する

新しい GitHub App の準備ができたら、以前の OAuth app のユーザーに新しい GitHub App への移行を指示します。 ユーザーを自動的に移行する方法はありません。 各ユーザーは、自分で GitHub App のインストール、承認、またはその両方を行う必要があります。

アプリ所有者は、新しい GitHub App のインストールや承認を行うことと、以前の OAuth app に対する承認を取り消すことをユーザーに促す行動喚起を組み込む必要があります。 ドキュメントまたはユーザー インターフェイス要素も更新する必要があります。

GitHub App のインストールをユーザーに求める

GitHub App がそれ自体の代理として API 要求や Organization またはリポジトリ リソースへのアクセスを行うようにする場合、ユーザーは GitHub App をインストールする必要があります。 ユーザーは自分のアカウントまたは Organization に GitHub App をインストールするときに、アプリがアクセスできるリポジトリを選び、アプリが要求した Organization とリポジトリのアクセス許可を付与します。

ユーザーが GitHub App をインストールできるように、アプリの Web ページへのリンクを追加できます。ユーザーはそれをクリックして、GitHub App をインストールできます。 インストール URL の形式は https://github.com/apps/YOUR_APP_NAME/installations/new です。 YOUR_APP_NAME を、GitHub App のスラッグ名に置き換えます。この名前は、GitHub App の設定ページの [パブリック リンク] フィールドにあります。

OAuth app でアクセスしていたリポジトリを事前に選ぶには、インストール URL に /permissions とクエリ パラメーターを追加できます。 これによりユーザーは、OAuth app で既にアクセスできているリポジトリへのアクセス権を GitHub App に付与できます。 クエリ パラメーターは次のとおりです。

• suggested_target_id: GitHub App をインストールするユーザーまたは Organization の ID。 このパラメーターは必須です。
• repository_ids[]: インストール用に選ぶリポジトリ ID。 省略すると、すべてのリポジトリが選ばれます。 事前選択できるリポジトリ数は、最大で100です。 OAuth app でアクセスできるリポジトリのリストを取得するには、認証されたユーザーのためのリポジトリのリストと Organization のリポジトリのリストのエンドポイントを使用します。

(例: 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 App のインストール」を参照してください。

アプリの承認をユーザーに求める

GitHub App でユーザーの代理として API 要求を行う場合、ユーザーがアプリを承認する必要があります。 ユーザーは、アプリを承認するときに、ユーザーの代わりに動作するためのアクセス許可をアプリに付与し、アプリから要求されたアカウント アクセス許可を付与します。 アプリが Organization アカウントにインストールされている場合、その Organization 内の各ユーザーは、アプリが自分の代わりに動作できるようにアプリを承認する必要があります。

ユーザーにアプリの承認を求めるために、Web アプリケーション フローまたはデバイス フローを介してユーザーを誘導します。 詳しくは、「GitHub アプリのユーザー アクセス トークンの生成」をご覧ください。

GitHub Apps の認可の詳細については、「GitHub App の承認」を参照してください。

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 を削除するには、added アクションを使用して installation_repositories Webhook をリッスンできます。 GitHub App がそのイベントを受け取ったら、REST API を使用して、OAuth app のそれらのリポジトリの Webhook を削除できます。 詳細については、「Webhook のイベントとペイロード」および「リポジトリ ウェブフック の REST API エンドポイント」を参照してください。

同様に、Organization の Webhook を削除するには、created アクションを使用して installation Webhook をリッスンできます。 GitHub App が Organization のイベントを受け取ったときに、REST API を使用して、その Organization の 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 Support に問い合わせて、マーケットプレースからアプリを削除することが必要な場合があります。