Checks APIを使ってみる

概要

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に記録されます。 自動フローを無効化した� �合、チェックスイートの作成エンドポイントを使ってチェックスイートを作成できます。 コミットにフィードバックを行うには、チェック実行の作成エンドポイントの使用を継続すべきです。

Checks APIのための書き込み権限は、GitHub Apps� けが利用できます。 OAuth App及び認証されたユーザは、チェック実行とチェックスイートを見ることができますが、作成することはできません。 GitHub Appを構築しているのでないなら、ステータスAPIに興味を引かれるかもしれません。

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

GitHub Appとして認証を受ける方法については「GitHub Appのための認証オプション」を参照してく� さい。

チェックの実行について

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

チェック実行が15日以上にわたり不完全な状態である� �合は、チェック実行のconclusionがstaleになり、GitHubに状態がと表示されます。 GitHubのみが、チェック実行をstaleとしてマークできます。 チェック実行で出る可能性がある結果についての詳細は、 conclusionパラメータを参照してく� さい。

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

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

Checks APIのための書き込み権限は、GitHub Apps� けが利用できます。 OAuth App及び認証されたユーザは、チェック実行とチェックスイートを見ることができますが、作成することはできません。 GitHub Appを構築しているのでないなら、ステータスAPIに興味を引かれるかもしれません。

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テストを作成する」を参照してく� さい。