Skip to main content

使用 REST API 与检查交互

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

概述

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

有关如何将 REST API 用于 GitHub App 的示例,请参阅“使用 GitHub 应用构建 CI 检查”。

你可以将这些状态与受保护的分支一起使用,可以防止人们过早合并拉取请求。 有关详细信息,请参阅“关于受保护分支”。

关于检查套件

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

status 可以是 queuedin_progresscompleted

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

  • action_required
  • cancelled
  • timed_out
  • failure
  • neutral
  • skipped
  • stale
  • startup_failure
  • 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_progresscompleted

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

  • action_required
  • cancelled
  • timed_out
  • failure
  • neutral
  • skipped
  • 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 设置请求的操作的详细示例,请参阅“使用 GitHub 应用构建 CI 检查”。

检查数据的保留期

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

要将拉取请求与必需且已存档的检查合并,必须重新运行检查。