Skip to main content
ドキュメントへの更新が� �繁に発行されており、このページの翻訳はま� 行われている� �合があります。最新情� �については、英語版のドキュメントをご覧く� さい。
� 

� 

このバージョンの GitHub Enterprise はこの日付をもって終了となりました: 2022-10-12. 重大なセキュリティの問題に対してであっても、パッチリリースは作成されません。 パフォーマンスの向上、セキュリティの向上、新機能の向上を図るために、最新バージョンの GitHub Enterprise にアップグレードします。 アップグレードに関するヘルプについては、GitHub Enterprise サポートにお問い合わせく� さい。

Checks APIを使ってみる

この記事では、次の� �目が扱われます。

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

概要

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

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

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

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

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

チェック スイートは、チェック スイートの conclusion の中で最も優先度の高いチェック実行 conclusion を� �告します。 たとえば、3 回のチェック実行で timed_out、success、neutral の結論が得られた� �合、チェック スイートの結論は timed_out になります。

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

デフォルトの自動的なフローを使いたくない� �合は、チェックスイートをいつ作成するかをコントロールできます。 チェック スイートの作成に関する既定の設定を変更するには、チェックスイートのリポジトリ環境設定の更新エンドポイントを使用します。 自動フロー設定に対するすべての変更は、リポジトリのAudit logに記録されます。 自動フローを無効にした� �合は、チェック スイートの作成エンドポイントを使用してチェック スイートを作成できます。 コミットに関するフィードバックを提供するには、引き続きチェック実行の作成エンドポイントを使用する必要があります。

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

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

GitHub アプリとして認証する方法については、GitHub アプリの認証オプションに関する記事を参照してく� さい。

チェックの実行について

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

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

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

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

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

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

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

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