Github 检查 API、检查运行、检查套件

Question

我想了解 Github Checks API，以便我可以使用它们来检索数据。在以下 Github 文档https://docs.github.com/en/rest/guides/getting-started-with-the-checks-api上，我能够得出检查运行与更改的 sha 相关联，并且在每个创建分支检查套件上的提交。检查 API 有助于获取所有这些信息。但我希望更清楚地了解其中三个的差异。谁能用简单的例子和​​术语解释这三个术语？

Answer 1

因此，首先，GitHub Commit Statuses API与 GitHub Checks API（包括套件和运行）是分开的，所以让我们先单独看看它们，然后我将解释它们之间的差异。

在我们开始讨论之前，我想区分PR Check和Check Run，以避免混淆。PR检查描述了 CI 或特定 PR 提交上其他地方运行的给定作业或任务的当前状态（尽量不要在这里说状态）。这些可以通过提交状态或检查运行来创建。下面粉红色框中的所有项目都是PR 检查，请注意隐藏所有检查按钮。

GitHub 状态 - API

我认为这是一个简单、通用的 API，用于报告给定提交的PR 检查。这很简单，不需要费力去显示给定提交的PR 检查的简单结果。该 API 也出现在检查 API 之前，因此它的功能稍弱一些。

优点

• 简单易用的API
• context与作为标识符的简单关系。
• 可以在PR Checks UI 上拥有完全可定制的文本描述。
• 您可以使用个人访问令牌（又名 PAT）以用户身份创建状态，而无需创建GitHub 应用程序，但也可以与GitHub 应用程序一起使用！

缺点

• 选项有限status，仅允许error、failure、pending、success、 无conclusion子集选项来定义已完成的作业，例如Check Runs。
• 没有工作时间或持续时间的概念。
• 没有状态分组，例如检查运行通过其GitHub 应用程序分组为检查套件
• 无注释
• 没有详细的output日志。这并不是太重要，因为您可以链接到实际PR 检查运行的 URL，例如在 CircleCI、Jenkins 等中。但是用户并不总是被授权查看这些运行，因此输出可能对开源存储库有所帮助具有非公开 CI。

GitHub 检查 - API

Checks API 是用于显示提交任务结果的最新、最好的工具，它基本上可以完成Commit Statuses API 可以做的所有事情，甚至更多。Check Runs属于一个Check Suite，一个Check Suite可以有多个Check Runs。每次提交（即每个GitHub 应用程序）只能有一个Check Suite，尝试为给定应用程序创建另一个 Check Suite 将只会返回之前创建的Check Suite。因此，新的Check Run会根据经过身份验证的GitHub App自动分配给Check Suite，您无法手动将 Run 分配给 Suites。head_sha

与状态相反，检查运行由自动生成的check_run_id而不是context字符串来标识。

我没有过多涉及Check Suites API ，因为它们实际上只是Check Runs的分组，这是不言自明的，并且它们不会影响任何PR Checks UI，只会影响检查中的Check Runs分组标签。需要注意的一件事是，默认情况下，您无需先创建检查套件即可创建检查运行，GitHub 只会为您创建一个新的检查套件。

优点

• 运行的status/的粒度更大。conclusion
• 显示PR 检查结果的强大功能。
• 可以通过 Markdown 中的输出摘要提供运行上下文。
• 可以为特定代码行创建注释，以添加有关所执行分析的信息，例如给定代码行的 linting 错误。这些将显示在 PR 文件选项卡 UI 中，类似于 PR 代码注释，以及带有任何其他检查运行输出的 PR 检查选项卡。
• 具有时间意识，可以毫不费力地自动报告持续时间。

缺点

• 需要管理的 API 和关系稍微复杂一些。
• PR UI 中的部分描述是根据status conclusion检查运行任务的持续时间自动生成的。
• 无法通过用户PAT创建，必须从经过身份验证的GitHub 应用程序创建。对此 API 的读取访问权限不需要作为GitHub App进行身份验证。

您可能不会遇到但很高兴知道的一种边缘情况：如果您要创建一个新的检查运行，name其与同一经过身份验证的应用程序下的现有检查运行完全相同。结果行为有点奇怪，但这样做会以相同的名称创建新的Check Run ，但不会删除现有的Check Run。但是，即使在 PR UI 中，Check Suite也不会看到或链接到现有的Check Run 。但！！如果您更改name其中任何一个，使得运行现在具有唯一的names，它将再次链接起来。似乎 GitHub 只是按日期排序，然后在Check Suite中查找Check Runs时按唯一名称进行过滤。这不适用于来自不同经过身份验证的应用程序的相同内容。names

比较

下面是用于比较提交状态API 和检查运行API之间类似选项的映射。它们并不完全是 1:1，但很相似。

提交状态	检查运行	选项说明
sha	head_sha	这些等效，但有一个小例外，即提交状态直接链接到sha，而head_sha链接到检查运行所属的检查套件。
context	name	用作标识符，但两者都定义PR UI 中PR 检查context的标题。由于“检查运行”是由选项跟踪的，因此选项可能会更改，而无需创建新的“检查运行”。情况并非如此，更改总是会创建新的提交状态。您可能没有使用同一GitHub App创建的检查运行的重复项，请参阅上面的注释。check_run_idnamecontextcontextnames
context*	external_id	这external_id是为了跟踪检查运行，而无需存储 id 或始终保持name常量。这只是与该选项有些相似，但仅用于识别Check Runcontext的目的。
description	output.title	这里的主要区别是，为description您提供了完整的工作空间，其中output.title将显示在自动生成的状态字符串之后。
target_url	details_url	它们在某种程度上是等效的，第一个区别是target_url除非定义，否则不会显示，而details_url默认为 PR UI 中的检查运行 URL。另一个区别是PR 检查UI上的“检查运行” 按钮将始终链接到“检查”页面，该页面将显示指向“如果已定义”的链接。Detailsdetails_url
state	status	它们非常相似，但允许的值略有不同，但实际上在 PR UI 中显示相同。
不适用	conclusion	这只是显示了PR 检查API的增强功能，您可以更精细地控制PR 检查状态，尽管 UI 上没有很大差异，请参阅下面的示例变化。
不适用	started_at	Commit Statuses没有类似的选项。
不适用	completed_at	Commit Statuses没有类似的选项。
不适用	actions	Commit Statuses没有类似的选项。
不适用	output	Commit Statuses没有类似的选项。
不适用	output.annotations	Commit Statuses没有类似的选项。

* 只是有些相似，而不是直接等同。

PR 检查 UI 组件映射

我进行了简单的PR 检查，并突出显示了提交状态API 和检查运行API之间的 UI 元素之间的差异。非常相似但略有不同。

以下是将选项与其对 PR Checks UI 的影响联系起来的示例变体。

提交状态变化

检查运行变化

如果检查运行处于不完整状态超过 14 天，则检查运行 conclusion将变为stale。只有 GitHub 可以将Check Runs标记为stale.

PR UI 中的“检查”选项卡

PR UI 中的“检查”选项卡将显示所有创建的检查套件及其子检查运行，并允许您设置选项output来控制此页面的内容。如果您也定义了这些，此页面也会images显示annotations。

最后一点：一旦创建，您就无法删除任何提交状态、检查运行或检查套件，只允许更新。由于这些状态是如此短暂，这没什么大不了的，但以防万一您想知道。

更新（2022 年 6 月 21 日）

我发现了另外两个怪癖需要解释。首先，details_urlfor Check Runs不会设置按钮的值Details，相反，该Details按钮实际上总是重定向到Checks页面，该页面具有指向 if Defined 的链接details_url。

其次，一旦将“检查运行” status设置为“检查运行'completed'”，就无法取消完成“检查运行”。但是您可以通过创建一个新的检查运行来解决这个问题，name并将其设置status为除 之外的其他内容'completed'。请参阅上面详细解释的带有name重复检查运行的边缘情况。

更新（2022 年 6 月 29 日）

如上所述，检查运行API 会跟踪运行的持续时间。请务必注意，started_at每当创建检查运行时，时间仅设置一次，无论定义如何status。例如，如果我触发 CI 构建并将所有作业设置status为queued，则作业运行持续时间将不准确。解决此问题的一个好方法是，started_at每当您将时间设置为 时，status始终设置时间in_progress。像（javascript）这样简单的东西const started_at = new Date().toISOString()就可以解决问题。