Checks APIを使ってみる

Check Runs APIを使うと、リポジトリのコード変更に対して強力なチェックを実行するGitHub Appを構築できます。継続的インテグレーション、コードの構文チェック、コードのスキャンサービスを実行し、コミットについて詳細なフィードバックを行うアプリを作成できます。

ここには以下の内容があります:

概要
チェックスイートについて
チェックの実行について
チェック実行とリクエストされたアクション

概要

GitHub Appは、単に合格/不合格の二択ではない、情報量の多いビルドステータスを報告し、コードの行について詳細な情報が付いたアノテーションをつけ、テストを再実行することができます。 Checks APIの機能は、GitHub Appのみで利用できます。

GitHub AppでChecks APIを利用する方法については、「Checks APIでCIテストを作成するを参照してください。

チェックスイートについて

誰かがリポジトリにコードをプッシュすると、その直近のコミットについてGitHubはチェックスイートを作成します。チェックスイートとは、特定のコミットに対して一つのGitHub Appにより作成されたチェック実行の集合のことです。チェックスイートは、スイートに含まれるチェックを実行し、ステータスとチェック結果をまとめます。

チェックスイートのワークフロー

チェックスイートは、チェックスイートのconclusionにおいて、実行したチェックの中で最も優先度が高いconclusionを報告します。たとえば、3つのチェックを実行した際にtimed_out、success、neutralの結果が出た場合、チェックスイートの結果はtimed_outとなります。

デフォルトでは、GitHubはリポジトリにコードがプッシュされると自動的にチェックスイートを作成します。デフォルトのフローでは、checks:write権限を持つすべてのGitHub Appに、check_suiteイベントが (requested アクションと共に) 送信されます。 GitHub Appがcheck_suiteイベントを受信すると、直近のコミットに対する新たなチェック実行を作成できます。 GitHubは、チェック実行のリポジトリおよびSHAに基づき、正しいチェックスイートに新しいチェック実行を自動的に追加します。

デフォルトの自動的なフローを使いたくない場合は、チェックスイートをいつ作成するかをコントロールできます。チェックスイートの作成についてのデフォルト設定を変更するには、チェックスイートのためのリポジトリプリファレンスの更新エンドポイントを使用します。自動フロー設定に対するすべての変更は、リポジトリのAudit logに記録されます。自動フローを無効化した場合、チェックスイートの作成エンドポイントを使ってチェックスイートを作成できます。コミットにフィードバックを行うには、チェック実行の作成エンドポイントの使用を継続すべきです。

Write permission for the Checks API is only available to GitHub Apps. OAuth Apps and authenticated users can view check runs and check suites, but they are not able to create them. If you aren't building a GitHub App, you might be interested in the Statuses API.

チェックスイートAPIを使用するには、GitHub Appはchecks:write権限が必要であり、またcheck_suite webhookにサブスクライブすることもできます。

For information on how to authenticate as a GitHub App, see "Authentication Options for GitHub Apps."

チェックの実行について

チェックの実行は、個別のテストであり、チェックスイートの一機能です。各実行にステータスと結果が含まれます。

チェック実行のワークフロー

check_suite webhookを受け取ったら、チェックが完了していなくてもすぐにチェック実行を作成できます。チェック実行のstatusは、queued、in_progress、またはcompletedの値で更新でき、より詳細を明らかにしてoutputを更新できます。チェック実行にはタイムスタンプ、詳細情報が記載された外部サイトへのリンク、コードの特定の行に対するアノテーション、および実行した分析についての情報を含めることができます。

チェック実行のアノテーション

チェック実行は、GitHub UIで手動で再実行することも可能です。詳細は「ステータスチェックについて」を参照してください。この場合、チェック実行を作成したGitHub Appは、新たなチェック実行を要求するcheck_run webhookを受け取ります。チェックスイートを作成せずにチェック実行を作成した場合、GitHubは自動的にチェックスイートを作成します。

Check Runs APIを使用するには、GitHub Appはchecks:write権限が必要であり、またcheck_run webhookにサブスクライブすることもできます。

チェック実行とリクエストされたアクション

チェック実行をリクエストされたアクション (GitHub Actionsと混同しないこと) で設定すると、 GitHubのプルリクエストビューでボタンを表示でき、そのボタンでGitHub Appに追加のタスクを実行するようリクエストできるます。

たとえば、コードの構文チェックを行うアプリケーションは、リクエストされたアクションを使って、検出した構文エラーを自動的に修正するボタンをプルリクエストに表示できます。

アプリケーションに追加のアクションをリクエストできるボタンを作成するには、チェック実行を作成する際にactions オブジェクトを使用します。たとえば、以下のactionsオブジェクトは、プルリクエストに「Fix this」というラベルのついたボタンを表示します。このボタンは、チェック実行が完了した後に表示されます。

"actions": [{
   "label": "Fix this",
   "description": "Let us fix that for you",
   "identifier": "fix_errors"
 }]

チェック実行のリクエストされたアクションのボタン

ユーザがボタンをクリックすると、GitHubはcheck_run.requested_action webhookをアプリケーションに送信します。アプリケーションがcheck_run.requested_action webhookイベントを受信すると、webhookペイロードからrequested_action.identifierキーを探し、どのボタンがクリックされたかを判断してリクエストされたタスクを実行することができます。

Checks APIで必要なアクションを設定する方法の詳しい例については、「Checks APIでCIテストを作成する」を参照してください。