Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

使用 REST API 与检查交互

可以使用 REST API 构建 GitHub Apps,针对存储库中的代码更改运行功能强大的检查。 您可以创建应用程序以执行持续集成 、代码分析或代码扫描服务,并提供有关提交的详细反馈。

概述

GitHub Apps 可以报告丰富的状态信息、提供详细的代码行注释以及重新运行测试,而不是提供二进制的通过/失败构建状态。 用于管理检查的 REST API 专用于 GitHub 应用。

有关如何将 REST API 用于 GitHub App 的示例,请参阅“Creating CI tests with the Checks API”。

关于检查套件

当有人向仓库推送代码时,GitHub 会为最新的提交创建一个检查套件。 检查套件是单个 GitHub 应用为特定提交而创建的检查运行的集合。 检查套件汇总了套件所含检查运行的状态和结论。

status 可以是 queuedin_progresscomplete

如果状态为 complete,则结论可以是以下任何一项:

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

检查套件在其 conclusion 中报告优先级最高的检查运行 conclusion。 例如,如果三个检查运行的结论分别为 timed_outsuccessneutral,则检查套件的结论将为 timed_out

默认情况下,当代码被推送到仓库时,GitHub 会自动创建一个检查套件。 此默认流程会将 check_suite 事件(使用 requested 操作)发送到具有 checks:write 权限的所有 GitHub 应用。 当 GitHub 应用收到 check_suite 事件时,它可以为最新的提交创建新的检查运行。 GitHub 根据检查运行的存储库和 SHA,自动将新的检查运行添加到适当的检查套件中。

如果您不想使用默认的自动流程,您可以控制何时创建检查套件。 若要更改用于创建检查套件的默认设置,请使用更新检查套件的存储库首选项终结点。 对自动流程设置的所有更改都被记录在仓库的审核日志中。 如果已禁用自动流,则可以使用创建检查套件终结点来创建一个检查套件。 应该继续使用创建检查运行终结点来提供对提交的反馈。

REST API 与检查交互的写入权限仅适用于 GitHub Apps。 OAuth Apps 和经过身份验证的用户可以查看检查运行和检查套件,但无法创建它们。 如果未生成 GitHub App,你可能对使用 REST API 与提交状态进行交互感兴趣。

若要使用终结点来管理检查套件,GitHub App 必须具有 checks:write 权限并且可以订阅 check_suite Webhook。

有关如何以 GitHub 应用身份进行身份验证的信息,请参阅 GitHub 应用的身份验证选项

关于检查运行

检查运行是检查套件中的单个测试。 每个运行都包含状态和结论。

状态可以是 queuedin_progresscomplete

如果状态为 completed,则结论可以是以下任何一项:

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

如果检查运行处于未完成状态超过 14 天,则检查运行的 conclusion 将变成 stale,并且通过 在 GitHub 上显示为过时。 只有 GitHub 可以将检查运行标记为 stale。 有关检查运行可能得出的结论的详细信息,请参阅 conclusion 参数

一旦收到 check_suite Webhook,即使检查尚未完成,也可以创建检查运行。 可以在检查运行完成时使用值 queuedin_progresscompleted 来更新其 status,并且可以在更多详细信息可用时更新 output。 检查运行可以包含时间戳、指向外部站点上更多详细信息的链接、特定代码行的详细注释以及有关所执行分析的信息。

注释将检查运行中的信息添加到特定代码行。 每个注释都包含一个 annotation_level 属性,可以是 noticewarningfailure。 注释还包括 pathstart_lineend_line,用于指定注释所引用的位置。 批注包含用于描述结果的 message。 有关详细信息,请参阅 REST API 参考文档中的“检查运行”。

还可以在 GitHub UI 中手动重新运行检查。 有关详细信息,请参阅“关于状态检查”。 发生这种情况时,创建检查运行的 GitHub 应用将收到请求新检查运行的 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 对象在拉取请求中显示一个按钮,标签为“修复此问题”。 该按钮在检查运行完成后显示。

"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 设置请求的操作的详细示例,请参阅“Creating CI tests with the Checks API”。