概览
GitHub 应用程序可以报告丰富的状态信息、提供详细的代码行注释以及重新运行测试,而不是提供二进制的通过/失败构建状态。 Checks API 功能专用于您的 GitHub 应用程序。
关于如何将检查 API 用于 GitHub 应用程序 的示例,请参阅“使用检查 API 创建 CI 测试”。
关于检查套件
当有人向仓库推送代码时,GitHub 会为最新的提交创建一个检查套件。 检查套件是单个 GitHub 应用程序为特定提交而创建的检查运行的集合。 检查套件汇总了套件所含检查运行的状态和结论。
检查套件在其 conclusion
中报告优先级最高的检查运行 conclusion
。 例如,如果三个检查运行的结论分别为 timed_out
、success
和 neutral
,则检查套件的结论将为 timed_out
。
默认情况下,当代码被推送到仓库时,GitHub 会自动创建一个检查套件。 此默认流程会将 check_suite
事件(使用 requested
操作)发送到具有 checks:write
权限的所有 GitHub 应用程序。 当您的 GitHub 应用程序收到 check_suite
事件时,它可以为最新的提交创建新的检查运行。 GitHub 根据检查运行的仓库和 SHA,自动将新的检查运行添加到适当的检查套件中。
如果您不想使用默认的自动流程,您可以控制何时创建检查套件。 要更改用于创建检查套件的默认设置,请使用更新检查套件的仓库首选项端点。 对自动流程设置的所有更改都被记录在仓库的审核日志中。 如果您禁用了自动流程,您可以使用创建检查套件端点来创建一个检查套件。 您应该继续使用创建检查运行端点来提供对提交的反馈。
检查 API 的写入权限仅适用于 GitHub 应用程序。 OAuth 应用程序和经过身份验证的用户可以查看检查运行和检查套件,但无法创建它们。 如果您没有构建 GitHub 应用程序,您可能对状态 API 感兴趣。
要使用检查套件 API,GitHub 应用程序必须具有 checks:write
权限并且可以订阅 check_suite web 挂钩。
有关如何验证为 GitHub 应用程序的信息,请参阅“GitHub 应用程序的身份验证选项”。
关于检查运行
检查运行是检查套件中的单个测试。 每个运行都包含状态和结论。
如果检查运行处于未完成状态超过 14 天,则检查运行的 conclusion
将变成 stale
,并且通过
在 GitHub 上显示为 stale(过时)。 只有 GitHub 可以将检查运行标记为 stale
。 有关检查运行之可能结论的更多信息,请参阅 conclusion
参数。
一旦收到 check_suite
web 挂钩,您即可创建检查运行,即使检查尚未完成。 您可以在检查运行完成时使用值 queued
、in_progress
或 completed
来更新其 status
, 并且可以在更多详细信息可用时更新 output
。 检查运行可以包含时间戳、指向外部站点上更多详细信息的链接、特定代码行的详细注释以及有关所执行分析的信息。
还可以在 GitHub UI 中手动重新运行检查。 更多信息请参阅“关于状态检查”。 发生这种情况时,创建检查运行的 GitHub 应用程序将收到请求新检查运行的 check_run
web 挂钩。 如果您创建检查运行时没有创建检查套件,GitHub 将自动为您创建检查套件。
检查 API 的写入权限仅适用于 GitHub 应用程序。 OAuth 应用程序和经过身份验证的用户可以查看检查运行和检查套件,但无法创建它们。 如果您没有构建 GitHub 应用程序,您可能对状态 API 感兴趣。
要使用检查运行 API,GitHub 应用程序必须具有 checks:write
权限并且可以订阅 ccheck_run web 挂钩。
检查运行和请求的操作
在设置带有请求操作(不要与 GitHub Actions 混淆)的检查运行时,您可以在 GitHub 上的拉取请求视图中显示一个按钮,以允许用户请求您的 GitHub 应用程序 执行额外任务。
例如,代码分析应用程序可以使用请求的操作在拉取请求中显示一个按钮,以自动修复检测到的语法错误。
要创建可从您的程序请求额外操作的按钮,请在创建检查运行时使用
actions
对象。 例如,下面的 actions
对象在拉取请求中显示一个按钮,标签为“Fix this(修复此问题)”。 该按钮在检查运行完成后显示。
"actions": [{
"label": "Fix this",
"description": "Let us fix that for you",
"identifier": "fix_errors"
}]
当用户单击该按钮时,GitHub 会将 check_run.requested_action
web 挂钩发送到您的应用程序。 当您的应用程序收到 check_run.requested_action
web 挂钩事件时,它可以在 web 挂钩有效负载中查找 requested_action.identifier
键,以确定单击了哪个按钮,并执行请求的任务。
关于如何使用检查 API 设置请求操作的详细示例,请参阅“使用检查 API 创建 CI 测试”。