GitHub アプリとは
ここでは、GitHub アプリとは何か、そのしくみ、およびそれを使用してワークフローを改善する方法について説明します。 他の人によって構築されたソリューションを採用する場合でも、自分のニーズを正確に満たすソリューションを開発する場合でも、プロセスを改善する余地は常にあります。
GitHub API を使用してプラットフォームを拡張する
GitHub では、開発者がプラットフォーム上でほとんど何でもできるようにする堅牢な API が提供されています。 これは REST エンドポイントを介して公開されているため、任意のプラットフォームやプログラミング言語から簡単に統合できます。 しかし、API アクセスはそれ自体では成り立ちません。 機能を他の人と共有したい開発者は、それをアプリとしてパッケージ化して公開し、だれでも使用できるようにする必要があります。
OAuth アプリと GitHub アプリのどちらをワークフローに組み込むかを選択する際には、いくつかの要素を考慮する必要があります。 このセクションでは、GitHub アプリと OAuth アプリの使用方法とアクセス許可の違い、およびイベント サブスクリプションについて説明します。
GitHub ワークフローをカスタマイズする際には、カスタム スクリプトの記述、独自の OAuth アプリの作成および認可、GitHub Marketplace から入手できる GitHub アプリのインストールなど、いくつかの機能を利用できます。 一般に、1 回限りのタスクにはスクリプトを使うのが最適です。 頻繁に実行する必要があるアクションについては、OAuth アプリと GitHub アプリの自動化を使用することで、ユーザーとユーザーのチームが時間を節約し、ワークフロー内で最適なレベルのセキュリティを維持できます。 GitHub アプリと OAuth アプリには多くの違いがあり、使用するアプリの決定に影響します。 これらの違いを前もって理解しておくと、問題の原因とやり直しの作業を事前に減らすことができます。また、ワークフロー内の特定のユース ケースに最適なアプリケーションを見つけるのに役立ちます。
このセクションの終了時には、GitHub アプリと OAuth アプリの違いや、状況に適したアプリの選択方法について十分理解できます。
アクセス権とアクセス許可の付与
アプリが GitHub リポジトリにアクセスできるようにするための最も重要な考慮事項の 1 つは、操作に必要なアクセス許可です。 信頼できるアプリもあれば、疑わしいアプリもあります。 確実に信頼できるアプリにアクセス許可を付与するようにしてください。
Note
すべてのアプリは、一意の API キーを使用して、リポジトリ内のデータに対する要求を行います。 アクセスを承認すると、それが承認するキーになります。 アプリのキーへのアクセスは、リポジトリの設定からいつでも取り消すことができます。
OAuth アプリの比較
OAuth アプリは、ユーザーの代わりに GitHub のデータにアクセスする方法を提供します。 ユーザーの代わりに行動するため、GitHub のライセンス許可された接続クライアントを消費することに注意する必要があります。 OAuth アプリは個人アカウントで作成して登録できます。管理者のアクセス許可を所有している場合は組織レベルで登録できます。 GitHub と統合する OAuth アプリは、どの種類のアクセスが組織またはリポジトリに必要かを明示します。 ユーザーが OAuth アプリを認可すると、データの読み取りや変更など、認証されたユーザーとして動作する機能がアプリに提供されます。 このアプローチは基本的に、ユーザーとして GitHub のデータを読み取り、書き込み、または編集するための、自動化された方法です。 認可は、ユーザーがアクセスできるリソースに限定されている点にも注意が必要です。ただし、OAuth アプリはユーザーが利用できる "すべての" リソースにもアクセスできます。
Note
アクセス レベルは、トークンのスコープ (ユーザー、組織、リポジトリ) で制限されます。
OAuth アプリのアクセス制限がある組織の場合は、管理者がアプリケーション使用の承認を付与できます。 イベント サブスクリプションを使用すると、OAuth アプリはアクティビティの発生時に応答します。
GitHub アプリ
対照的に、GitHub アプリはユーザーの個人アカウント、ユーザーが所有する組織、またはユーザーが管理者のアクセス許可を所有する特定のリポジトリに "インストール" されます。 GitHub アプリは OAuth アプリのように個別のユーザーではなく、サービスとしてインストールされ、GitHub とやり取りを行います。 GitHub アプリの利点の 1 つは、OAuth アプリとは異なり、GitHub アプリが GitHub のライセンスが許可されたシートを消費しないことです。
GitHub アプリは JWT トークン (JSON Web トークン) の署名に使用される秘密キーを介して、アプリケーション自体の代わりにデータにアクセスします。 これらは特定のリポジトリにインストールされるため、ユーザーはアプリがアクセスできるリポジトリを選択して、アプリがアクセスできるデータの量を制限できます。 アクセス許可は、GitHub アプリが API 経由でアクセスできるリソースを定義します。 OAuth アプリとは異なり、GitHub アプリにはリポジトリ データ、issue、pull request に対するカスタマイズ可能なアクセス許可があります。 これにより、より詳細なアクセス許可を付与して、アプリの読み取りと書き込みをアクセスが許可されているリポジトリのみに制限できます。 組織内の GitHub アプリの設定を管理できるのは、組織の所有者だけです。
GitHub アプリは、GitHub Marketplace で見つけてインストールすることができます。 GitHub アプリを検索するときは、一部のアプリに検証済みバッジが付いていることに注意してください。 このバッジは、ドメインの所有権が検証済みであり、GitHub サポートによりメール アドレスが確認されており、2 要素認証を必要とする組織によってアプリが所有されていることを示しています。
- 管理者は、リポジトリの管理、チェック、リポジトリの内容、デプロイ、および問題に関するアクセス許可を付与できます (管理者の変更にはユーザーの同意が必要です)
- 管理者はアプリのユーザーに、別のユーザー、メール、フォロワー、GPG キー、Git SSH キー、主演、視聴をブロックするアクセス許可を付与できます (管理者の変更にはユーザーの同意が必要です)
- イベント サブスクリプション: Security advisory、Check suite、Create、Deployment、Fork、Label、Member、Check in、Commit comment、Delete、Deployment status、Milestone、Membership、Organization (管理者は GH App の UI で構成します。変更も可能です)
GitHub アプリと OAuth アプリの選択
GitHub アプリは、場合によってはワークフローに統合するための理想的な方法になりますが、大企業にとっては、自動化のために OAuth アプリを使用していた従来の方法から移行することが困難になることもあります。 たとえば、セキュリティ ポリシーの制限により、これらのツールの使用を選択する際の管理者オプションが制限される場合もあります。
注意
システム管理者は開発者と協力して、セキュリティ ポリシーに従いながら、これらのアプリケーションを活用して自動化に最適なオプションを見つける必要があります。
ユーザーの状況に適したソリューションのアプリを判断するために、考慮する必要がある重要な質問を次に示します。
- アプリをユーザーとして機能させる必要がありますか?
- レート制限はどれくらい必要ですか?
- 組織とリポジトリでアプリにどのようなアクセス許可を付与する必要がありますか?
- このアプリはセキュリティ ポリシーに準拠していますか?
GitHub アプリと OAuth アプリのどちらかを選択する際に考慮する必要がある重要な特性と違いを次に示します。
| GitHub アプリ | OAuth アプリの比較 |
|---|---|
| GitHub アプリをインスールすると、アプリはユーザーまたは組織アカウントの選択されたリポジトリにアクセスできるようになります。 | OAuth アプリを認可すると、ユーザーのアクセス可能なリソース (たとえば、アクセスできるリポジトリ) へのアクセス権がアプリに付与されます。 |
| インストール アクセス トークンは、アプリケーションの作成者が選択したアクセス許可を所有する、指定されたリポジトリに制限されます。 | OAuth アクセス トークンは、スコープで制限されます。 |
| インストール トークンは、アプリを GitHub アプリのボットとして識別します。 | アクセス トークンは、アプリをアプリにトークンを付与したユーザーとして識別します。 |
| GitHub アプリには、必要なものにだけアクセスを要求できるようにする、対象を絞ったアクセス許可があります。 | OAuth アプリでは、詳細なアクセス許可は使用できません。 |
| GitHub アプリは組織のアプリケーション ポリシーの対象ではありません。 GitHub アプリは組織の所有者が許可したリポジトリにのみアクセスできます。 | 組織のアプリケーション ポリシーがアクティブな場合、組織の所有者のみが OAuth アプリのインストールを認可できます。 OAuth アプリがインストールされている場合、アプリは承認された組織内で組織の所有者が所持しているトークンで表示できるすべてのものにアクセスできます。 |
| レート制限の増加は、GitHub アプリ レベル (すべてのインストールに影響) と個々のインストール レベルの両方で許可できます。 | レート制限の増加は、OAuth アプリごとに許可されます。 その OAuth アプリに許可されたトークンはすべて、制限が増加します。 |
| GitHub アプリはユーザーの代わりに認証できます。これは、ユーザーからサーバーへの要求と呼ばれます。 認可するフローは OAuth アプリの認可フローと同じです。 ユーザーからサーバーへのトークンは期限切れになることがあり、更新トークンで更新できます。 | OAuth アプリによって使用される OAuth フローは、ユーザーの代わりに OAuth アプリを認可します。 これは、GitHub アプリのユーザーからサーバーへの認可で使用されるフローと同じものです。 |
| GitHub アプリはリポジトリの内容へのアクセス許可を要求し、インストール トークンを使用して、HTTP ベースの Git 経由で認証を行います。 | OAuth アプリは write:public_key スコープを要求し、API 経由でデプロイ キーを作成します。 その後、そのキーを使用して Git コマンドを実行できます。 |
アプリケーションのアクセスとアクセス許可
アプリが GitHub リポジトリにアクセスできるようにするための最も重要な考慮事項の 1 つは、操作に必要なアクセス許可です。 信頼できるアプリもあれば、疑わしいアプリもあります。 確実に信頼できるアプリにアクセス許可を付与するようにしてください。
GitHub アプリと OAuth アプリのどちらを使用するかの決定は、アプリがアクセスする必要があるアクセスのレベルによって異なります。 一般に、タスクを実行するには、スコープが最小のツールを使用するようにチームに勧める必要があります。 OAuth アプリは、ユーザーまたは組織の所有者のすべてのリソースにアクセスできます。
- OAuth アプリには、GitHub データへの読み取りまたは書き込みアクセス権を付与できます
- GitHub アプリには、あるアカウントへのアクセス権を付与し、別のアカウントへのアクセス権を付与しないことができます。
アプリケーションのセキュリティ
アプリケーションに脆弱性が見つかった場合は、セキュリティ ポリシーの範囲内で、優先的にプロジェクトのユーザーへ通知する必要があります。 セキュリティの問題を迅速に伝えることは、ユーザーが侵害されたトークンを取り消すことと、機密データを公開することの違いを意味する可能性があります。 トークンはパスワードよりも安全性が高くなりますが、それでもセキュリティが侵害される可能性があるため、組織で準備しておくことが重要です。
README.md ファイルの他に、リポジトリに SECURITY.md ファイルを追加することをお勧めします。 SECURITY.md ファイルでは、リポジトリのセキュリティ関連情報が強調表示されます。 ファイルには、セキュリティの連絡先、組織のポリシー、および脆弱性が発見されたときに実行する応答の詳細が含まれている必要があります。
イベントへの反応
GitHub アプリはパッシブになるように設計されています。 何かが起こるのを待ってから、通常は GitHub API を介して反応します。 GitHub でイベントが発生するのを待機しているときは、Webhook とポーリングの 2 つのアプローチがあります。
Note
GitHub アプリは、GitHub データの操作に限定されていません。 他のソースから発生するイベントを待機したり、他のサービスを更新するアクションを実行したりすることも簡単にできます。
GitHub Webhook の使用
Webhook は、イベント処理に推奨されるアプローチです。 Webhook のスコープ内で GitHub に何かが起きると、直ちに動作が開始されます。 Webhook からは、アプリがリアルタイムでリッスンして処理できる通知がプッシュされます。 Webhook はリポジトリの設定で構成できます。これにはイベントの種類、認証、HTTP 通知の配信方法などが含まれます。
ポーリング
Webhook を選択できない場合もあります。 GitHub が直接アクセスできない企業のファイアウォールの内側にアプリを配置する必要がある場合があります。 その場合の代替方法は、GitHub API を使用して追跡しているデータをポーリングすることです。
Webhook リレー
ファイアウォールの内側にあるアプリをポーリングする代わりに、smee.io などの Webhook 転送サービスを使用することもできます。 この方法では、パブリック サービスが、リポジトリの Webhook をサブスクライブしてから、ファイアウォールの内側で実行されているクライアント サービスに受信データを中継します。 そのクライアント サービスは、その後、通知が元のソースから送信されたかのように、実行中のアプリに通知をプッシュします。