# REST API を使用してチェックを操作する REST API を使用して、リポジトリ内のコード変更に対して強力なチェックを実行する GitHub Apps を構築できます。 継続的インテグレーション、コードの構文チェック、コードのスキャンサービスを実行し、コミットについて詳細なフィードバックを行うアプリを作成できます。 ## 概要 バイナリの成功/失敗のビルド状態ではなく、 GitHub Apps は豊富な状態を報告したり、詳細情報を使用してコード行に注釈を付けたり、テストを再実行したりできます。 チェックを管理するための REST API は、GitHub Apps でのみ使用できます。 GitHub Appで REST API を使用する方法の例については、[GitHub アプリを使用した CI チェックのビルド](/ja/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app#step-26-automatically-fix-rubocop-errors) を参照してください。 ステータスを[保護されたブランチ](/ja/enterprise-server@3.22/rest/repos#branches)で使うと、プル リクエスト早まってマージされるのを防ぐことができます。 詳しくは、「[保護されたブランチについて](/ja/enterprise-server@3.22/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging)」をご覧ください。 ## チェックスイートについて 誰かがリポジトリにコードをプッシュすると、GitHubは最後のコミットのチェックスイートを作成します。 チェック スイートは、特定のコミットに対して 1 つのGitHub アプリによって作成された[check runs](/ja/enterprise-server@3.22/rest/checks#check-runs) のコレクションです。 チェックスイートは、スイートに含まれるチェックを実行し、ステータスとチェック結果をまとめます。 `status` が取り得るのは `queued`、`in_progress`、`requested`、`waiting`、`pending`、`completed` です。 GitHub Actions、`requested`、または`waiting`の状態を設定できるのは、`pending`だけです。 状態が `completed`、結論は次のいずれかになります。 * `action_required` * `cancelled` * `timed_out` * `failure` * `neutral` * `skipped` * `stale` * `startup_failure` * `success` チェック スイートは、チェック スイートの `conclusion` の中で最も優先度の高いチェック実行 `conclusion` を報告します。 たとえば、3 回のチェック実行で `timed_out`、`success`、`neutral` の結論が得られた場合、チェック スイートの結論は `timed_out` になります。 既定では、コードGitHubリポジトリにプッシュされると、チェック スイートが自動的に作成されます。 この既定のフローでは、`check_suite` イベント (`requested` アクションを使用) が、`checks:write` アクセス許可を持つすべてのGitHub Apps に送信されます。 GitHub アプリは、`check_suite` イベントを受け取ると、最新のコミットに対する新しいチェック実行を作成できます。 GitHubは、チェック実行のリポジトリと SHA に基づいて、正しい [check suite](/ja/enterprise-server@3.22/rest/checks#check-suites) に新しいチェック実行を自動的に追加します。 デフォルトの自動的なフローを使いたくない場合は、チェックスイートをいつ作成するかをコントロールできます。 チェック スイートの作成に関する既定の設定を変更するには、[チェックスイートのリポジトリ環境設定の更新](/ja/enterprise-server@3.22/rest/checks/suites#update-repository-preferences-for-check-suites)エンドポイントを使用します。 自動フロー設定に対するすべての変更は、リポジトリのAudit logに記録されます。 自動フローを無効にした場合は、[チェック スイートの作成](/ja/enterprise-server@3.22/rest/checks/suites#create-a-check-suite)エンドポイントを使用してチェック スイートを作成できます。 コミットに関するフィードバックを提供するには、引き続き[チェック実行の作成](/ja/enterprise-server@3.22/rest/checks/runs#create-a-check-run)エンドポイントを使用する必要があります。 チェックを操作する REST API の書き込み許可は、GitHub Apps に対してのみ使用できます。 OAuth apps および認証済みユーザーは、チェック実行とチェック スイートを表示することができますが、作成することはできません。 GitHub App をビルドしていない場合、この REST API を使って[コミット状態](/ja/enterprise-server@3.22/rest/commits#commit-statuses)を操作することが考えられます。 エンドポイントを使用してチェック スイートを管理するには、 GitHub App に `checks:write` アクセス許可が必要であり、 [check\_suite](/ja/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_suite) Webhook をサブスクライブすることもできます。 GitHub アプリとして認証する方法については、「[GitHub アプリでの認証について](/ja/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app)」を参照してください。 ## チェックの実行について チェックの実行は、個別のテストであり、チェックスイートの一機能です。 各実行にステータスと結果が含まれます。 `status` が取り得るのは `queued`、`in_progress`、`requested`、`waiting`、`pending`、`completed` です。 GitHub Actions、`requested`、または`waiting`の状態を設定できるのは、`pending`だけです。 状態が `completed`、結論は次のいずれかになります。 * `action_required` * `cancelled` * `timed_out` * `failure` * `neutral` * `skipped` * `success` チェック実行が14日を超えて未完了の状態のままである場合、そのチェック実行の`conclusion`は`stale`になり、GitHubでは付きの古いものとして表示されます。 チェック実行をGitHubとしてマークできるのは、`stale`だけです。 チェック実行で出る可能性のある結論の詳細については、[`conclusion` パラメーター](/ja/enterprise-server@3.22/rest/checks#create-a-check-run--parameters)を参照してください。 [ `check_suite` ](/ja/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_suite) Webhook を受け取るとすぐに、チェックが完了していない場合でも、チェック実行を作成できます。 チェック実行が値 `status`、`queued`、または `in_progress` で完了したら、チェック実行の `completed` を更新できます。さらに詳細が入手できるにつれ `output` を更新できます。 チェック実行にはタイムスタンプ、詳細情報が記載された外部サイトへのリンク、コードの特定の行に対するアノテーション、および実行した分析についての情報を含めることができます。 注釈を使って、チェック実行時の情報をコードの特定の行に追加します。 各注釈には `annotation_level` プロパティを含めます。これには `notice`、`warning`、または `failure` を指定できます。 注釈がどの場所を参照するかを指定するには、注釈に `path`、`start_line`、`end_line` も含めます。 結果を説明するには、注釈に `message` を含めます。 詳しくは、「[チェック実行用 REST API エンドポイント](/ja/enterprise-server@3.22/rest/checks/runs)」をご覧ください。 GitHub UI でチェックを手動で再実行することもできます。 詳細については、「[状態の確認](/ja/enterprise-server@3.22/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks)」を参照してください。 この場合、チェックの実行を作成した GitHub App は、新しいチェックの実行を要求する [`check_run`](/ja/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) webhook を受け取ります。 チェック スイートを作成せずにチェック実行を作成した場合、GitHub がチェック スイートを自動的に作成します。 チェックを操作する REST API の書き込み許可は、GitHub Apps に対してのみ使用できます。 OAuth apps および認証済みユーザーは、チェック実行とチェック スイートを表示することができますが、作成することはできません。 GitHub App をビルドしていない場合、この REST API を使って[コミット状態](/ja/enterprise-server@3.22/rest/commits#commit-statuses)を操作することが考えられます。 エンドポイントを使用してチェックの実行を管理するには、 GitHub App に `checks:write` アクセス許可が必要であり、 [check\_run](/ja/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) Webhook をサブスクライブすることもできます。 ## チェックの実行状況とリクエストされたアクション 要求されたアクション ( GitHub Actionsと混同しないように) を使用してチェック実行を設定すると、 GitHub の pull request ビューにボタンを表示して、ユーザーが GitHub App に追加のタスクを実行するように要求できます。 たとえば、コードの構文チェックを行うアプリケーションは、リクエストされたアクションを使って、検出した構文エラーを自動的に修正するボタンをプルリクエストに表示できます。 アプリから追加のアクションを要求できるボタンを作成するには、`actions`際に\[[](/ja/enterprise-server@3.22/rest/checks/runs#create-a-check-run--parameters)オブジェクト]\(/rest/checks#create-a-check-run)を使用します。 たとえば、以下の `actions` オブジェクトは、pull request の **\[チェック]** タブに \[Fix this] というラベルのついたボタンを表示します。 このボタンは、チェック実行が完了した後に表示されます。 ```json "actions": [{ "label": "Fix this", "description": "Let us fix that for you", "identifier": "fix_errors" }] ``` ユーザーがボタンをクリックすると、GitHub`check_run.requested_action`[webhook](/ja/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) がアプリに送信されます。 アプリが `check_run.requested_action` Webhook イベントを受信すると、Webhook ペイロード内の `requested_action.identifier` キーを検索して、どのボタンがクリックされたかを判断し、要求されたタスクを実行できます。 REST API を使って要求されたアクションを設定する方法の詳細な例については、「[GitHub アプリを使用した CI チェックのビルド](/ja/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app)」を参照してください。 ## チェック データの保持 サイト管理者は、お使いの GitHub Enterprise Server インスタンス 上のチェックデータの保持ポリシーを設定できます。 詳しくは、「[アプリケーションの構成](/ja/enterprise-server@3.22/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-applications#enabling-retention-policy-for-checks)」をご覧ください。 必須であり、アーカイブされているチェックと pull request をマージするには、チェックを再実行する必要があります。