アプリケーションでのGitHub APIの利用

はじめに

このガイドは、GitHub Appをビルドしてサーバー上で実行するのに役立ちます。ビルドするアプリケーションは、アプリケーションがインストールされたリポジトリでオープンされたすべての新しいIssueにラベルを付けます。

このプロジェクトでは、以下を見ていきます。

イベントを待ち受けるアプリケーションのプログラミング
Octokit.rbライブラリを使ったREST APIの操作の実行

メモ: このガイドでは、Ruby プログラミング言語を使用したアプリ開発のプロセスを示します。た� し、Octokit にはさまざまな決まりごとがあります。 JavaScript を使用する� �合は、Probot と Node.js を使用して GitHub アプリを開発できます。

以下のステップを行っていけば、GitHub APIの完全な一式を使って他の種類のインテグレーションを開発する準備が整います。

前提条件

以下に関する基本的な理解があると役立つでしょう。

とはいえ、経験のレベルにかかわらず見ていくことはできます。その過程で必要な情� �にはリンクしていきます！

始める前に、以下を行っておく必要があります。

アプリでの GitHub API の使用リポジトリをクローンします。
```
$ git clone https://github.com/github-developer/using-the-github-api-in-your-app.git
```
ディレクトリの中には、このクイックスタートで使うテンプレートコードを含む template_server.rb ファイルと、完成したプロジェクトコードを含む server.rb ファイルがあります。
開発環境のセットアップに関するクイックスタートの手� �に従い、template_server.rb アプリサーバーを構成して実行します。開発環境のセットアップ以外の GitHub App のクイックスタートを以前に完了している� �合は、 "新しい" GitHub App を登録し、このクイックスタートで使用する新しい Smee チャネルを開始する必要があります。

このクイックスタートには、開発環境のセットアップに関するクイックスタートと同じ template_server.rb コードが含まれています。注: 開発環境のセットアップに関するクイックスタートに従って、アプリでの GitHub API の使用リポジトリに含まれているプロジェクトファイルを必ず使用してく� さい。

テンプレート GitHub App の設定で問題が発生する� �合は、「トラブルシューティング」セクションをご覧く� さい。

アプリケーションのビルド

template_server.rb のコードに馴染ん� ところで、アプリケーションがインストールされたリポジトリでオープンされたすべての issue に自動的に needs-response ラベルを追� するコードを作成しましょう。

この template_server.rb ファイルには、ま� カスタマイズされていないアプリテンプレートコードが含まれています。このファイルには、webhookイベントを処理するためのプレースホルダーのコードや、Octokit.rbクライアントを初期化する他のコードが含まれています。

注: template_server.rb には、このガイドを補完し、追� の技術的な詳細を説明する多くのコードコメントが含まれています。このセクションの先に進む前に、コードの動作の概要をつかむために、この時点でこのファイル中のコメントを読み通しておくと役立つかもしれません。

このガイドの終わりまでに作成するカスタマイズされた最終コードは、server.rb にあります。とはいえ、最後までそれを見るのは待ってみてく� さい!

以下が、最初のGitHub Appを作成するまでに行うステップです。

アプリのアクセス許可を更新する
イベント処理の追�
新しいラベルの作成
ラベルの処理の追�

手� � 1. アプリのアクセス許可を更新する

最初にアプリを登録したときは、既定のアクセス許可を受け入れました。これは、アプリがほとんどのリソースにアクセスできないことを意味します。この例においては、アプリケーションはIssueを読み、ラベルを書く権限を必要とします。

アプリケーションの権限を更新するには、以下の手� �に従います。

アプリの設定ページでアプリを選び、サイドバーの [アクセス許可と Webhook] をクリックします。
[アクセス許可] セクションで [Issue] を探し、その横にある [アクセス] ドロップダウンで [読み取りと書き込み] を選びます。このオプションはIssueとラベルの両方へのアクセスを許可するものと説明されており、これはまさに必要なことです。
[イベントのサブスクライブ] セクションで、 [Issue] を選んでイベントをサブスクライブします。
ページの下部にある [変更の保存] をクリックします。
アプリケーションを自分のアカウントにインストールしたなら、メールをチェックして、新しい権限を受諾するリンクに従ってく� さい。アプリケーションの権限あるいはwebhookを変更した� �合、そのアプリケーションをインストールしたユーザ（自分自身を含む）は、変更が有効になる前に新しい権限を承認しなければなりません。インストールページに移動し、アプリの横にある [構成] をクリックして、新しいアクセス許可を受け入れることもできます。アプリケーションが異なる権限を要求していることを知らせるバナーがページの上部に表示されます。 "Details（詳細）"をクリックし、"Accept new permissions（新しい権限を承認）"をクリックしてく� さい。

すばらしい。アプリケーションは必要なタスクを実行する権限を所有しています。これで、アプリケーションを動作させるコードを追� できるようになりました。

手� � 2. イベント処理の追�

アプリケーションが最初にやらなければならないのは、オープンされた新しいIssueを待ち受けることです。 Issue イベントをサブスクライブしたので、特定の issue 関連のアクションが発生したときにトリガーされる issues Webhook の受信を開始します。コード中にほしい特定のアクションに対してこのイベントの種類をフィルターできます。

GitHub は、Webhook ペイロードを POST 要求として送信します。 Smee Webhook ペイロードを http://localhost/event_handler:3000 に転送したため、サーバーは post '/event_handler' ルートで POST 要求のペイロードを受信します。

空の post '/event_handler' ルートは、「前提条件」セクションでダウンロードした template_server.rb ファイルに既に含まれています。空のルートは次のようになっています。

  post '/event_handler' do

    # # # # # # # # # # # #
    # ADD YOUR CODE HERE  #
    # # # # # # # # # # # #

    200 # success status
  end

以下のコードを追� することで、このルートを使って issues イベントを処理します。

case request.env['HTTP_X_GITHUB_EVENT']
when 'issues'
  if @payload['action'] === 'opened'
    handle_issue_opened_event(@payload)
  end
end

GitHub が送信する全てのイベントには、HTTP_X_GITHUB_EVENT という要求ヘッダーが含まれており、これは POST 要求でのイベントの種類を示します。この時点では、関心があるのはissues というイベントの種類� けです。各イベントには、イベントをトリガーしたアクションの種類を示す追� の action フィールドがあります。 issues の� �合、action フィールドは assigned、unassigned、labeled、unlabeled、opened、edited、milestoned、demilestoned、closed、または reopened になります。

イベントハンドラをテストするには、一時的なヘルパーメソッドを追� してみてく� さい。後でラベル処理を追� するときに更新します。この時点では、コードの helpers do セクションの中に以下のコードを追� してく� さい。他の任意のヘルパーメソッドの前後に新しいメソッドを追� できます。 � �序は問題ではありません。

def handle_issue_opened_event(payload)
  logger.debug 'An issue was opened!'
end

このメソッドはJSON形式のイベントペイロードを引数として受け取ります。これは、メソッド中でペイロードをパースして、任意の必要なデータへとドリルダウンしていけるということです。どこかの時点でペイロード全体を調べると役立つかもしれません。logger.debug 'An issue was opened! を logger.debug payload に変更してみてく� さい。表示されるペイロード構� は、issues Webhook イベントドキュメントに表示されているものと一致している必要があります。

すばらしい。変更をテストしてみましょう。

注: 変更をテストする前に、Sinatra サーバーを再起動する必要があります。 Ctrl-C キーを押してサーバーを停止し、ruby template_server.rb を再度実行します。アプリのコードを変更するたびにこの作業を行いたくない� �合は、再読み込みに関するページを確認してく� さい。

ブラウザで、アプリケーションをインストールしたリポジトリにアクセスしてく� さい。そのリポジトリで新しいIssueをオープンしてく� さい。そのIssueは好きな内容でかまいません。これは単にテストにすぎません。

ターミナルを見直してみれば、An issue was opened! というメッセージが出力にあるはずです。おめでとうございます! アプリケーションにイベントハンドラを追� できました。 💪

手� � 3. 新しいラベルの作成

これで、アプリケーションはIssueがオープンされたときを示せるようになりました。今度は、アプリケーションがインストールされたリポジトリの新しくオープンされた任意の issue に needs-response というラベルを追� しましょう。

ラベルを任意の� �所に追� する前に、リポジトリにカスタ� ラベルを作成する必要があります。これをする必要があるのは一度� けです。このガイドのためには、ラベルをGitHub上で手動で作成します。リポジトリで、 [Issue] 、 [ラベル] 、 [新しいラベル] の� �にクリックします。新しいラベルに needs-response という名前を付けます。

ヒント: アプリでラベルをプログラ� から作成できたら� 晴らしいのではないでしょうか? できます。このガイドのステップを終えた後に、自分でそのためのコードを追� してみてく� さい。

ラベルが存在するようになったので、REST API を使用して新しくオープンした issue にラベルを追� するようにアプリをプログラミングできます。

手� � 4. ラベルの処理の追�

おめでとうございます。最後のステップである、アプリケーションへのラベル処理の追� にまで来ました。このタスクでは、Octokit.rb Ruby ライブラリを使用します。

Octokit.rb ドキュメントで、メソッドの一覧を見つけます。使用するメソッドは add_labels_to_an_issue です。

template_server.rb に戻って、前に定義したメソッドを見つけます。

def handle_issue_opened_event(payload)
  logger.debug 'An issue was opened!'
end

add_labels_to_an_issue ドキュメントでは、このメソッドに 3 つの引数を渡す必要があることがわかります。

リポジトリ ("owner/name" 形式の文字列)
Issue number(integer)
Labels (array)

ペイロードをパースすれば、リポジトリとIssue番号を取得できます。ラベル名は常に同じ (needs-response) なので、labels 配列にハードコードした文字列で渡せます。これらのピースをまとめると、更新されたメソッドは以下のようになるでしょう。

# When an issue is opened, add a label
def handle_issue_opened_event(payload)
  repo = payload['repository']['full_name']
  issue_number = payload['issue']['number']
  @installation_client.add_labels_to_an_issue(repo, issue_number, ['needs-response'])
end

新しいIssueをテストのリポジトリでオープンして、何が起こるか見てみてく� さい! もしすぐには何も起こらなければ、リフレッシュしてみてく� さい。

ターミナルにはあまり表示されませんが、ボットユーザーが問題にラベルを追� していることがわかります。

メモ： GitHub Apps が API を介してラベルの追� などのアクションを実行すると、これらのアクションが ボット アカウントによって実行されていると表示GitHub。詳しくは、「マシンアカウントとボットアカウント」をご覧く� さい。

そうなっていたら、おめでとうございます! 動作するアプリケーションの構築に成功しました! 🎉

最終的なコードは、server.rbアプリテンプレートリポジトリで確認できます。

ここから移動できる� �所に関するアイデアについては、「次のステップ」を参照してく� さい。

トラブルシューティング

以下は、いくつかの一般的な問題と推奨される解決策です。他の問題が生じた� �合は、で助けやアドバイスを求めることができます。

Q: サーバーがイベントをリッスンしていません。 Smeeクライアントはターミナルウィンドウで動作していて、新しいIssueをオープンしてGitHub.com上でイベントを送信していますが、サーバーを動作させているターミナルウィンドウに出力がありません。

A: アプリ設定の Smee ドメインが正しくないかもしれません。アプリ設定ページにアクセスし、「新しいアプリを GitHub に登録する」に示されているフィールドを再確認します。これらのフィールドのドメインが、「新しい Smee チャンネルの開始」の smee -u <unique_channel> コマンドで使用したドメインと一致していることを確認します。
Q: アプリが機能しません。新しいIssueをオープンしましたが、リフレッシュしてもラベルが追� されません。

A: 次のすべてに該当することを確認してく� さい。
- issue を開いているリポジトリにアプリをインストールした。
- Smee クライアントがターミナルウィンドウで実行されている。
- Web サーバーが別のターミナルウィンドウでエラーなしで実行されている。
- アプリには、issue に対する読み取りおよび書き込みアクセス許可があり、issue イベントをサブスクライブしている。
- アクセス許可を更新した後にメールを確認し、新しいアクセス許可を受け入れた。

まとめ

このガイドを見終えれば、GitHub Appを開発するための基本的なビルディングブロックを学ん� ことになります! 振り返ると、以下を行いました。

イベントを待ち受けるようにアプリケーションをプログラ�
Octokit.rbライブラリを使ったREST APIの操作

次の手� �

以下は、次に行えることのいくつかのアイデアです。

GraphQL を使用してアプリを書き換える。
Probot を使用して Node.js でアプリを書き換える。
needs-response ラベルが issue に既にあるかをアプリで確認して、なければ追� する。
ボットがラベルを追� できたら、ターミナルにメッセージを表示する。 (ヒント: メッセージの条件として needs-response ラベルの ID をペイロードのラベルの ID と比較し、他のラベルではなく関連するラベルが追� されたときにのみメッセージが表示されるようにします)
ランディングページをアプリに追� し、それに対する Sinatra ルートを接続する。
コードをホストされたサーバー（Herokuのような）に移す。新しいドメインでアプリケーションの設定を更新するのを忘れないようにしてく� さい。
でプロジェクトを共有したりアドバイスをもらったりする。