Webhook と GitHub Apps について
Webhook を使用すると、誰かがコミットをプッシュしたり、アプリがアクセスできるリポジトリでプル要求を開いたりしたときなど、GitHub Appでイベントが発生したときに、GitHubがリアルタイム通知を受け取ることができます。 Webhook の詳細については、「webhook について」を参照してください。 GitHub Appで Webhook を使用する方法を示すチュートリアルについては、webhook イベントに応答するGitHub アプリの構築 を参照してください。
GitHub Appで特定のイベントの Webhook を受信し、それらに対して自動的にアクションを実行するようにGitHubを構成できます。 受け取ることができる Webhook の種類については、「Webhook のイベントとペイロード」を参照してください。
GitHub App で Webhook イベントを受信するには、GitHub App の登録で Webhook を有効にし、GitHub が Webhook ペイロードを送信する Webhook URL を指定する必要があります。
GitHub Appが webhook に応答する必要がない場合、または認証にのみ使用される場合は、GitHub App登録の webhook 関数をオフにすることができます。 Webhook URL を指定する必要はありません。
GitHub Appの登録の詳細については、GitHub アプリの登録 を参照してください。 GitHub App登録が登録されている webhook を変更する方法について詳しくは、GitHub アプリの登録の変更を参照してください。
現時点では、Enterprise にインストールされたアプリは Webhook をサポートしていません。 Webhook を受信するには、組織にインストールする必要があります。
Webhook URL の選択
GitHub App の登録でWebhookを有効にする場合は、Webhook URLを指定する必要があります。 webhook URL は、 GitHub Appに送信された webhook イベント ペイロードを受信する Web サーバーのアドレスです。 その後、サーバーでペイロードの内容に基づいてアクションを実行できるようになります。 GitHub App が処理する Webhook トラフィック量に適した Web サーバーを選択する必要があります。
開発とテスト用の Webhook URL の選択
アプリの開発中とテスト中に、Smee などの Webhook ペイロード配信サービスを使用して、Webhook ペイロードをキャプチャし、ローカル開発環境に転送することができます。 Smee チャネルは認証されておらず、セキュリティで保護されていないため、運用環境のアプリケーションには Smee を使用しないでください。 または、ngrok、localtunnel、Hookdeck Console などのツールを使って、ローカル コンピューターをインターネットに公開してペイロードを受け取ることもできます。
Smee を使用した Webhook URL の作成
Smee を使用すると、ローカル開発をインターネットに公開することなく、 GitHub が Webhook ペイロードを送信できる一意のドメインを作成できます。 Smee では、この一意のドメインを "Webhook プロキシ URL" と呼びます。 Smee の Webhook プロキシ URL は、 GitHub Appの Webhook URL として使用できます。
- Smee を使用して一意のドメインを作成するには、 https://smee.io に移動し、 [新しいチャネルを開始する] をクリックします。
- Smee のチャネル ページで、[CLI を使用する] の下の指示に従って、Smee クライアントをインストールして実行します。
- Smee webhook URL を GitHub Appに接続するには、 GitHub App 登録ページの [Webhook URL] フィールドに一意の Smee ドメインを入力します。 詳細については、「GitHub アプリの登録」および「GitHub アプリの登録の変更」を参照してください。
運用環境用の Webhook URL の選択
受け取る Webhook トラフィックの量が少ない運用環境のアプリケーションについては、任意の動的アプリケーション サーバーにホストできます。 Webhook を処理するためのサーバー側コードは、イベントを受信し、その JSON ペイロードを逆シリアル化し、実行するアクション (データベースへのデータの格納や GitHub API の呼び出しなど) を決定できます。
運用環境の大規模なアプリで大量の Webhook トラフィックを処理するには、専用サーバーで非同期 Webhook 処理を使用することを検討してください。 これは、キューを導入することで実現できます。これにより、Webhook ハンドラーからキューにデータがプッシュされ、イベントに基づいて別個のプロセスにより後続のアクションが実行されます。 さらに、
Webhook シークレットを使用した Webhook のセキュリティ保護
ペイロードを受け取るようにサーバーを構成すると、サーバーに送信されるあらゆるペイロードをリッスンするようになります。 セキュリティ上の理由から、受信要求は、 GitHubからの要求のみに制限する必要があります。 これを行うには、アプリの Webhook シークレットを作成します。
GitHub アプリの webhook シークレットを作成するには、GitHub App登録ページの [Webhook シークレット] にシークレット トークンを入力します。 エントロピーの高いランダムな文字列を選択してください。 詳細については、「GitHub アプリの登録」および「GitHub アプリの登録の変更」を参照してください。
アプリの Webhook シークレットを作成した後は、Webhook シークレット トークンを安全に格納して検証するようにサーバーを構成する必要があります。 詳しくは、「Webhook 配信を検証する」をご覧ください。
Webhook イベントの購読
GitHub Appをサブスクライブして、特定のイベントの Webhook ペイロードを受信できます。 GitHub App の登録で選択できる具体的な Webhook イベントは、アプリに対して選択したアクセス許可の種類によって決まります。 まず、アプリに付与するアクセス許可を選択する必要があります。これで、そのアクセス許可のセットに関連する Webhook イベントにアプリをサブスクライブできます。 詳細については、 AUTOTITLE を参照してください。
たとえば、リポジトリで新しいイシューが開かれるたびにアプリで Webhook イベント ペイロードを受け取るようにする場合は、まず、[リポジトリのアクセス許可] で [イシュー] にアクセスするためのアクセス許可をアプリに付与する必要があります。 これで、[イベントにサブスクライブする] で [イシュー] を選択できます。
各 Webhook イベントに必要なアクセス許可の詳細については、「Webhook のイベントとペイロード」を参照してください。