使用 REST API 与检查交互

概述

GitHub Apps 可以报告丰富的状态，使用详细信息注释代码行，并重新运行测试，而不是二进制通过/失败构建状态。管理检查的 REST API 仅对您的 GitHub Apps 可用。

有关如何将 REST API 与 GitHub App 一起使用的示例，请参阅“使用 GitHub App 构建 CI 检查”。

您可以将状态与受保护分支一起使用，以防止用户过早合并拉取请求。更多信息，请参阅“关于受保护分支”。

关于检查套件

当有人将代码推送到代码库时，GitHub 会为最后一次提交创建一个检查套件。检查套件是单个 GitHub App 为特定提交创建的检查运行的集合。检查套件总结了套件包含的检查运行的状态和结论。

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。例如，如果三个检查运行的结论是timed_out、success和neutral，则检查套件结论将为timed_out。

默认情况下，当代码推送到代码库时，GitHub 会自动创建一个检查套件。此默认流程会将check_suite事件（带requested操作）发送给具有checks:write权限的所有 GitHub Apps。当您的 GitHub App 收到check_suite事件时，它可以为最新的提交创建新的检查运行。GitHub 会根据检查运行的代码库和 SHA 自动将新的检查运行添加到正确的检查套件中。

如果您不想使用默认的自动流程，您可以控制创建检查套件的时间。要更改检查套件创建的默认设置，请使用更新检查套件的代码库首选项端点。对自动流程设置的所有更改都记录在代码库的审计日志中。如果您禁用了自动流程，则可以使用创建检查套件端点创建检查套件。您应该继续使用创建检查运行端点来提供有关提交的反馈。

与检查交互的 REST API 的写入权限仅对 GitHub Apps 可用。OAuth 应用程序和已认证用户可以查看检查运行和检查套件，但无法创建它们。如果您没有构建 GitHub App，您可能希望使用 REST API 与提交状态交互。

要使用端点管理检查套件，GitHub App 必须具有checks:write权限，并且还可以订阅check_suite Webhook。

有关如何以 GitHub App 身份进行身份验证的信息，请参阅“关于使用 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参数。

收到check_suite Webhook 后，您可以创建检查运行，即使检查未完成。您可以使用值queued、in_progress或completed更新检查运行的status，并在更多详细信息可用时更新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 应用程序和已认证用户可以查看检查运行和检查套件，但无法创建它们。如果您没有构建 GitHub App，您可能希望使用 REST API 与提交状态交互。

要使用端点管理检查运行，GitHub App 必须具有checks:write权限，并且还可以订阅check_run Webhook。

检查运行和请求的操作

当您使用请求的操作设置检查运行（不要与 GitHub Actions 混淆）时，您可以在 GitHub 上的拉取请求视图中显示一个按钮，允许用户请求您的 GitHub App 执行其他任务。

例如，代码整理应用程序可以使用请求的操作在拉取请求中显示一个按钮，以自动修复检测到的语法错误。

要创建可以请求应用程序执行其他操作的按钮，请在创建检查运行时使用actions对象。例如，下面的actions对象在拉取请求的**检查**选项卡中显示一个标有“修复此问题”的按钮。该按钮在检查运行完成后显示。

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

当用户点击按钮时，GitHub 会将check_run.requested_action 网络钩子 发送到您的应用。当您的应用收到 check_run.requested_action 网络钩子事件时，它可以在网络钩子负载中查找 requested_action.identifier 密钥，以确定点击了哪个按钮并执行请求的任务。

有关如何使用 REST API 设置请求操作的详细示例，请参阅“使用 GitHub 应用构建 CI 检查”。

检查数据保留

GitHub 保留检查数据 400 天。400 天后，数据将存档。存档 10 天后，数据将永久删除。

要合并同时需要且已存档的检查的拉取请求，必须重新运行检查。