GitHub Apps を構築するためのクイック スタート

はじめに

GitHub Apps を使うと、プロセスを自動化したり、他のプラットフォームを GitHub と統合したりできます。 詳細については、「GitHub App の作成について」を参照してください。

このクイックスタートでは、GitHub App をすばやく作成する方法について説明します。 アプリにアクセス権が付与されているリポジトリで pull request が開かれると、アプリは pull request にコメントを追加します。

このクイックスタートでは、すぐに作業を開始できるように、事前に記述されたコードを使用します。 コードの記述に役立つ詳細なチュートリアルについては、「Webhook イベントに応答する GitHub App の構築」を参照してください。

前提条件

コンピューターまたは codespace では、Node.js のバージョン 12 以上を使用する必要があります。 詳しくは、Node.js のページを参照してください。

手順 1: アプリ コードを複製する

すぐに開始できるように、使用できるコードを記述しました。 自分でコードを記述する方法については、「Webhook イベントに応答する GitHub App の構築」を参照してください。

1. github/github-app-js-sample リポジトリを複製します。 詳しくは、「リポジトリをクローンする」をご覧ください。 ローカル クローンまたは GitHub Codespaces を使用できます。
2. ターミナル ウィンドウで、複製が格納されているディレクトリに移動します。
3. npm install を実行して依存関係をインストールします。

手順 2: Webhook プロキシ URL を取得する

アプリをローカルで開発するには、Webhook プロキシ URL を使って、GitHub からお使いのコンピューターまたは codespace に Webhook を転送できます。 このクイックスタートでは、Smee.io を使って Webhook プロキシ URL を指定し、Webhook を転送します。

1. ブラウザーで https://smee.io/ にアクセスします。
2. [Start a new channel] (新しいチャネルの開始) をクリックします。
3. [Webhook Proxy URL] (Webhook プロキシ URL) の下にある完全な URL をコピーします。 この URL は、後の手順で使用します。

手順 3: GitHub App を登録する

次の手順では、このクイックスタートに必要なアプリ設定を構成する方法について説明します。 設定の詳細については、「GitHub App の登録」を参照してください。

1. GitHub の任意のページの右上隅にある、自分のプロファイル写真をクリックします。
2. アカウント設定にアクセスしてください。
   • 個人用アカウントが所有するアプリの場合は、[設定] をクリックします。
   • 組織が所有するアプリの場合:
     1. [自分の組織] をクリックします。
     2. 組織の右側にある [設定] をクリックします。
3. 左側のサイドバーで [ 開発者設定] をクリックします。
4. 左側のサイドバーで、 [GitHub Apps] をクリックします。
5. [新しい GitHub App] をクリックします。
6. [GitHub App 名] に、アプリの名前を入力します。 たとえば、USERNAME-quickstart-app です。USERNAME はご自身の GitHub ユーザー名です。
7. [ホームページの URL] に「https://github.com/github/github-app-js-sample#readme」と入力します。
8. このクイックスタートでは、「ユーザーの特定と認可」と「インストール後」のセクションはスキップします。 これらの設定の詳細については、「GitHub App の登録」を参照してください。
9. [Webhook] の下で [アクティブ] が選択されていることを確認します。
10. [Webhook URL] の下に、前の Webhook プロキシ URL を入力します。 詳細については、「手順 2: Webhook プロキシ URL を取得する」を参照してください。
11. [Webhook シークレット] に、ランダムな文字列を入力します。 この文字列は後で使用します。
12. [リポジトリのアクセス許可] で、[pull request] の横にある [読み取りおよび書き込み] を選択します。
13. [イベントのサブスクライブ] で、 [pull request] を選択します。
14. [この GitHub App をインストールできる場所] で、 [このアカウントのみ] を選択します。
15. [GitHub App を作成する] をクリックします。

手順 4: 識別情報と資格情報を格納する

このクイックスタートでは、アプリの資格情報と識別情報を環境変数として .env ファイルに格納します。 アプリをデプロイするときに、資格情報の保存方法を変更することをお勧めします。 詳細については、「アプリの配置」を参照してください。

資格情報をローカルに格納するため、以下の手順を実行する前に、ご自分がセキュリティで保護されたコンピューターで作業していることを確認してください。

.env ファイルを作成します。

複製されたリポジトリには、.gitignore ファイルに .env が含まれています。 こうすることで、アプリの資格情報を誤ってコミットするのを防ぐことができます。 .gitignore ファイルの詳細については、「ファイルを無視する」を参照してください。

1. github/github-app-js-sample の複製が格納されているディレクトリに移動します。

2. このディレクトリの最上位レベルに .env という名前のファイルを作成します。

3. 次の内容を .env ファイルに追加します。 値は後の手順で更新します。

   Text

   APP_ID="YOUR_APP_ID"
   WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
   PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
   

アプリ設定に移動する

アプリの作成後にアプリ設定から移動した場合は、アプリの設定ページに移動します。

1. GitHub の任意のページの右上隅にある、自分のプロファイル写真をクリックします。
2. アカウント設定にアクセスしてください。
   • 個人用アカウントが所有するアプリの場合は、[設定] をクリックします。
   • 組織が所有するアプリの場合:
     1. [自分の組織] をクリックします。
     2. 組織の右側にある [設定] をクリックします。
3. 左側のサイドバーで [ 開発者設定] をクリックします。
4. 左側のサイドバーで、 [GitHub Apps] をクリックします。
5. アプリの名前の横にある [編集] をクリックします。

アプリの資格情報と識別情報を取得する

1. アプリの設定ページで、[アプリ ID] の横にある自分のアプリのアプリ ID を確認します。
2. .env ファイルで、YOUR_APP_ID を自分のアプリのアプリ ID に置き換えます。
3. アプリの設定ページの [秘密キー] で、 [秘密キーの生成] をクリックします。 お手元のコンピュータにダウンロードされた PEM フォーマットの秘密鍵が表示されます。 詳しくは、「GitHub Apps の秘密キーの管理」をご覧ください。
4. codespace を使用している場合は、ダウンロードした PEM ファイルを codespace に移動して、codespace がファイルにアクセスできるようにします。
5. .env ファイルで、YOUR_PRIVATE_KEY_PATH を秘密キーへの完全なパス (.pem 拡張子を含む) に置き換えます。
6. .env ファイルで、YOUR_WEBHOOK_SECRET をアプリの Webhook シークレットに置き換えます。 Webhook シークレットを忘れた場合は、[Webhook シークレット (省略可能)] の下の [シークレットの変更] をクリックします。 新しいシークレットを入力し、 [変更の保存] をクリックします。

手順 5: アプリをインストールする

アプリでリポジトリの pull request にコメントを残すには、リポジトリを所有するアカウントでアプリをインストールし、そのリポジトリへのアクセス許可を付与する必要があります。 アプリはプライベートであるため、アプリを所有するアカウントでのみインストールできます。

1. 作成したアプリを所有するアカウントで、アプリをインストールする新しいリポジトリを作成します。 詳しくは、「新しいリポジトリの作成」をご覧ください。
2. アプリの作成後にアプリ設定から移動した場合は、アプリの設定ページに移動します。 詳細については、「アプリ設定に移動する」を参照してください。
3. [パブリック ページ] をクリックします。
4. [インストール] をクリックします。
5. [選択したリポジトリのみ] を選択します。
6. [リポジトリの選択] ドロップダウン メニューを選択し、このセクションのはじめに選択したリポジトリをクリックします。
7. [インストール] をクリックします。

手順 6: サーバーを起動する

テストのために、ご自身のコンピューターまたは codespace をサーバーとして使います。 アプリは、サーバーが実行中のときにのみアクティブです。

1. ターミナル ウィンドウで、github/github-app-js-sample の複製が格納されているディレクトリに移動します。

2. Smee.io から転送された Webhook を受信するには、npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook を実行します。 WEBHOOK_PROXY_URL を、Webhook プロキシ URL に置き換えます。 URL を忘れた場合は、アプリの設定ページの [Webhook URL] フィールドで確認できます。

   次のような出力が表示されます。WEBHOOK_PROXY_URL は Webhook プロキシ URL です。

   Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook
   Connected WEBHOOK_PROXY_URL
   

3. 2 つ目のターミナル ウィンドウで、github/github-app-js-sample の複製が格納されているディレクトリに移動します。

4. npm run server を実行します。 ターミナルに Server is listening for events at: http://localhost:3000/api/webhook と表示されるはずです。

手順 7: アプリをテストする

これでサーバーが実行され、転送された Webhook イベントを受信するようになったので、pull request を開いてアプリをテストします。

1. 「手順 5: アプリをインストールする」で作成したリポジトリで pull request を開きます。 詳しくは、「pull request の作成」をご覧ください。
2. smee.io の Webhook プロキシ URL に移動します。 pull_request イベントが表示されます。 これは、pull request を作成したときに GitHub から正常に pull request イベントが送信されたことを示しています。
3. npm run server を実行したターミナルには、"#1 の pull request イベントを受信しました" のようなメッセージが表示されます。# の後の整数は、開いた pull request の番号です。
4. pull request のタイムラインに、アプリからのコメントが表示されます。 コメントでは、複製されたリポジトリ内の message.md ファイルの内容が使用されます。
5. 両方のターミナル ウィンドウで、Ctrl+C キーを押してサーバーを停止し、転送された Webhook のリッスンを停止します。

次の手順

これでアプリができたので、アプリのコードを拡張し、アプリをデプロイし、アプリを公開することができます。

アプリのコードを変更する

github/github-app-js-sample リポジトリをフォークし、さまざまな Webhook イベントに応答するか、さまざまな API 要求を行うためにコードを変更します。 コードの詳細については、「Webhook イベントに応答する GitHub App の構築」を参照してください。

行いたい API 要求や受信したい Webhook イベントのためにアプリに追加のアクセス許可が必要になる場合は、忘れずにアプリのアクセス許可を更新してください。 詳しくは、「GitHub アプリのアクセス許可を選択する」をご覧ください。

アプリのデプロイ

このチュートリアルでは、コンピューターまたは codespace をサーバーとして使用しました。 アプリを運用環境で使用する準備ができたら、アプリを専用サーバーにデプロイする必要があります。 たとえば、Azure App Service を使用できます。

サーバーを用意したら、アプリの設定で Webhook の URL を更新します。 運用環境では Webhook を転送するために Smee.io を使用しないでください。

また、コード内の port 定数と host 定数も更新する必要もあります。 詳しくは、「Webhook イベントに応答する GitHub App の構築」をご覧ください。

アプリの秘密キーや Webhook シークレットは絶対に公開しないでください。 このチュートリアルでは、gitignore の .env ファイルにアプリの資格情報を格納しました。 アプリをデプロイする際に、資格情報を保存する安全な方法を選び、それに応じて値を取得するようにコードを更新する必要があります。 たとえば、アプリをデプロイするサーバー上の環境変数に資格情報を保存できます。 Azure Key Vault などのシークレット管理サービスを使うこともできます。

アプリを共有する

アプリを他のユーザーや組織と共有したい場合は、アプリを公開します。 詳しくは、「GitHub Appをパブリックまたはプライベートにする」をご覧ください。

ベスト プラクティスに従う

GitHub App に関するベスト プラクティスに従うようにする必要があります。 詳しくは、「GitHub App を作成するためのベスト プラクティス」をご覧ください。