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

はじめに

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

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

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

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

必要な環境

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

• GitHub Apps
• webhook
• プログラミング言語のRuby
• REST API
• Sinatra

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

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

1. Using the GitHub API in your appリポジトリのクローン。

   $ git clone https://github.com/github-developer/using-the-github-api-in-your-app.git

   ディレクトリの中には、このクイックスタートで使用する template_server.rb ファイルと、完成したプロジェクトコードである server.rb ファイルがあります。

2. 開発環境のセットアップクイックスタート中のステップに従い、template_server.rbアプリケーションサーバーを設定し、実行してください。 開発環境のセットアップ以外のGitHub Appクイックスタートを完了させたことがあるなら、_新しい_GitHub Appを登録して、このクイックスタートで使う新しいSmeeチャンネルを開始してください。

   このクイックスタートには、開発環境のセットアップクイックスタートと同じtemplate_server.rbコードが含まれています。 ノート: 開発環境のセットアップクイックスタートを見ていく際には、必ずUsing the GitHub API in your appリポジトリに含まれているプロジェクトをファイルを使ってください。

   テンプレートのGitHub Appのセットアップで問題が生じた場合は、トラブルシューティングのセクションを参照してください。

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

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

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

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

1. アプリケーションの権限の更新
2. イベント処理の追加
3. 新しいラベルの作成
4. ラベルの処理の追加

ステップ 1. アプリケーションの権限の更新

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

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

1. アプリケーションの設定ページからアプリケーションを選択し、サイドバーの [Permissions & Webhooks] をクリックします。
2. "Permissions（権限）"セクションで"Issues"を見つけ、隣の"Access（アクセス）"ドロップダウンでRead & Write（読み書き）を選択してください。 このオプションはIssueとラベルの両方へのアクセスを許可するものと説明されており、これはまさに必要なことです。
3. "Subscribe to events（イベントのサブスクライブ）"セクションで、Issuesを選択してこのイベントをサブスクライブしてください。
4. Click Save changes at the bottom of the page.
5. If you've installed the app on your account, check your email and follow the link to accept the new permissions. Any time you change your app's permissions or webhooks, users who have installed the app (including yourself) will need to accept the new permissions before the changes take effect. You can also accept the new permissions by navigating to your installations page and clicking on "Configure" next to your app. You'll see a banner at the top of the page letting you know that the app is requesting different permissions. Click "Details" and click "Accept new permissions."

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

ステップ 2. イベント処理の追加

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

GitHub は webhook ペイロードを POST リクエストとして送信します。 Smeeのwebhookペイロードはhttp://localhost/event_handler:3000に転送しているので、サーバーはこのPOSTリクエストのペイロードをpost '/event_handler'ルートで受け取ります。

空の 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イベントのドキュメントに示されているものと一致しているはずです。

これでうまくいきます! 変更をテストしてみましょう。

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

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

ステップ 3. 新しいラベルの作成

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

ラベルをどこでも追加できるようにするには、リポジトリでカスタムラベルを作成しなければなりません。 これをする必要があるのは一度だけです。 このガイドのためには、ラベルをGitHub上で手動で作成します。 リポジトリでIssuesをクリックして、続いてLabelsを、そしてNew label（新規ラベル）をクリックしてください。 新しいラベルの名前を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つの引数を渡さなければならないとあります。

• Repo ("owner/name"という形式のstring)
• Issue number(integer)
• Labels (array)

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

# Issueがオープンされたらラベルを追加
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をテストのリポジトリでオープンして、何が起こるか見てみてください! もしすぐには何も起こらなければ、リフレッシュしてみてください。

ターミナルにはあまり表示されませんが、とはいえボットユーザがラベルをIssueに追加したことはわかります。

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

server.rbの最終のコードはアプリケーションのテンプレートリポジトリにあります。

ここから進む先に関するアイデアについては「次のステップ」を参照してください。

トラブルシューティング

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

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

  A: アプリケーション設定のSmeeドメインが正しくないかもしれません。 アプリケーション設定ページにアクセスし、Register a new app with GitHub（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のような）に移す。 新しいドメインでアプリケーションの設定を更新するのを忘れないようにしてください。
• GitHub API Development and Support Forumでプロジェクトを共有したりアドバイスをもらったりする。