Enterprise Server 3.20 は、現在リリース候補として使用できます。

REST API を使用してチェックを操作する

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

この記事で

概要

GitHub Apps は、合格と不合格の 2 つのビルド状態ではなく、情報量の多い状態を報告し、詳細な情報でコード行に注釈を付け、テストを再実行することができます。 チェックを管理するための REST API は、GitHub Apps でのみ使用できます。

REST API を GitHub App で使う方法の例については、「GitHub アプリを使用した CI チェックのビルド」を参照してください。

ステータスを保護されたブランチで使うと、プル リクエスト早まってマージされるのを防ぐことができます。 詳しくは、「保護されたブランチについて」をご覧ください。

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

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

          `status` が取り得るのは `queued`、`in_progress`、`requested`、`waiting`、`pending`、`completed` です。 
          `requested`、`waiting`、または `pending` の状態を設定できるのは、GitHub Actions のみです。

状態が 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 に新しいチェック実行を自動的に追加します。

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

チェックを操作する REST API の書き込み許可は、GitHub Apps に対してのみ使用できます。 OAuth apps および認証済みユーザーは、チェック実行とチェック スイートを表示することができますが、作成することはできません。 GitHub App をビルドしていない場合、この REST API を使ってコミット状態を操作することが考えられます。

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

GitHub アプリとして認証する方法については、「GitHub アプリでの認証について」を参照してください。

チェックの実行について

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

          `status` が取り得るのは `queued`、`in_progress`、`requested`、`waiting`、`pending`、`completed` です。 
          `requested`、`waiting`、または `pending` の状態を設定できるのは、GitHub Actions のみです。

状態が completed の場合、結論は次のいずれかになります。

  • action_required
  • cancelled
  • timed_out
  • failure
  • neutral
  • skipped
  • success

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

          [
          `check_suite`
          ](/webhooks-and-events/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 エンドポイント」をご覧ください。

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

チェックを操作する REST API の書き込み許可は、GitHub Apps に対してのみ使用できます。 OAuth apps および認証済みユーザーは、チェック実行とチェック スイートを表示することができますが、作成することはできません。 GitHub App をビルドしていない場合、この REST API を使ってコミット状態を操作することが考えられます。

エンドポイントを使ってチェックの実行を管理するには、GitHub App に checks:write アクセス許可が必要であり、check_run Webhook をサブスクライブすることもできます。

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

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

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

アプリから追加のアクションを要求できるボタンを作成するには、チェックランを作成する際にactionsオブジェクトを使用します。 たとえば、以下の actions オブジェクトは、pull request の [チェック] タブに [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 キーを検索して、どのボタンがクリックされたかを判断し、要求されたタスクを実行できます。

REST API を使って要求されたアクションを設定する方法の詳細な例については、「GitHub アプリを使用した CI チェックのビルド」を参照してください。

チェック データの保持

必須であり、アーカイブされているチェックと pull request をマージするには、チェックを再実行する必要があります。