# 使用 REST API 与检查交互 可以使用 REST API 生成 GitHub Apps 针对存储库中的代码更改运行强大的检查。 您可以创建应用程序以执行持续集成 、代码分析或代码扫描服务，并提供有关提交的详细反馈。 ## 概述 GitHub Apps 不同于只有通过/失败两种结果的构建状态，还可以报告丰富的状态信息，为代码行标注详细信息，并重新运行测试。 用于管理检查的 REST API 专用于GitHub应用。 有关如何将 REST API 与 a GitHub App配合使用的示例，请参阅 [使用 GitHub 应用构建 CI 检查](/zh/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app#step-26-automatically-fix-rubocop-errors)。 你可以将这些状态与[受保护的分支](/zh/enterprise-server@3.22/rest/repos#branches)一起使用，可以防止人们过早合并拉取请求。 有关详细信息，请参阅“[关于受保护分支](/zh/enterprise-server@3.22/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging)”。 ## 关于检查套件 当某人将代码推送到存储库时，GitHub为上次提交创建检查套件。 检查套件是单个 GitHub 应用为特定提交而创建的[检查运行](/zh/enterprise-server@3.22/rest/checks#check-runs)的集合。 检查套件汇总了其所包含检查运行的状态和结果。 `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 应用。 当 GitHub 应用程序收到 `check_suite` 事件时，它可以为最新提交创建新的检查运行单元。 GitHub会根据检查运行所属的存储库和 SHA，自动将新的检查运行添加到正确的 [check suite](/zh/enterprise-server@3.22/rest/checks#check-suites) 中。 如果您不想使用默认的自动流程，您可以控制何时创建检查套件。 若要更改用于创建检查套件的默认设置，请使用[更新检查套件的存储库首选项](/zh/enterprise-server@3.22/rest/checks/suites#update-repository-preferences-for-check-suites)终结点。 对自动流程设置的所有更改都被记录在仓库的审核日志中。 如果已禁用自动流，则可以使用[创建检查套件](/zh/enterprise-server@3.22/rest/checks/suites#create-a-check-suite)终结点来创建一个检查套件。 应该继续使用[创建检查运行](/zh/enterprise-server@3.22/rest/checks/runs#create-a-check-run)终结点来提供对提交的反馈。 REST API 与检查交互的写入权限仅适用于 GitHub Apps。 OAuth apps 和经过身份验证的用户可以查看检查运行和检查套件，但无法创建它们。 如果未生成 GitHub App，你可能对使用 REST API 与[提交状态](/zh/enterprise-server@3.22/rest/commits#commit-statuses)进行交互感兴趣。 若要使用这些端点来管理检查套件，GitHub App 必须具有 `checks:write` 权限，还可以订阅 [check\_suite](/zh/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_suite) Webhook。 有关如何作为 GitHub Apps 进行身份验证的信息，请参阅“[关于使用 GitHub 应用进行身份验证](/zh/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-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` 参数](/zh/enterprise-server@3.22/rest/checks#create-a-check-run--parameters)。 一旦收到 [`check_suite`](/zh/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_suite) Webhook，即使检查尚未完成，也可以创建检查运行。 可以在检查运行完成时使用值 `status`、`queued` 或 `in_progress` 来更新其 `completed`，并且可以在更多详细信息可用时更新 `output`。 检查运行可以包含时间戳、指向外部站点上更多详细信息的链接、特定代码行的详细注释以及有关所执行分析的信息。 注释将检查运行中的信息添加到特定代码行。 每个注释都包含一个 `annotation_level` 属性，可以是 `notice`、`warning` 或 `failure`。 注释还包括 `path`、`start_line` 和 `end_line`，用于指定注释所引用的位置。 批注包含用于描述结果的 `message`。 有关详细信息，请参阅“[检查运行的 REST API 终结点](/zh/enterprise-server@3.22/rest/checks/runs)”。 还可以在 GitHub UI 中手动重新运行检查。 有关详细信息，请参阅“[状态检查](/zh/enterprise-server@3.22/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks)”。 发生这种情况时，创建该检查运行的 GitHub App 将收到请求新检查运行的 [`check_run`](/zh/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) webhook。 如果您在不创建检查套件的情况下创建检查运行，GitHub 会自动为您创建检查套件。 REST API 与检查交互的写入权限仅适用于 GitHub Apps。 OAuth apps 和经过身份验证的用户可以查看检查运行和检查套件，但无法创建它们。 如果未生成 GitHub App，你可能对使用 REST API 与[提交状态](/zh/enterprise-server@3.22/rest/commits#commit-statuses)进行交互感兴趣。 若要使用这些端点来管理检查运行，GitHub App 必须具有 `checks:write` 权限，也可以订阅 [check\_run](/zh/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) webhook。 ## 检查运行和请求的操作 当你设置带有请求操作的检查运行时（不要与 GitHub Actions 混淆），你可以在 GitHub 上的拉取请求视图中显示一个按钮，让用户请求你的 GitHub App 执行其他任务。 例如，代码分析应用程序可以使用请求的操作在拉取请求中显示一个按钮，以自动修复检测到的语法错误。 若要创建一个可以从你的应用程序请求额外操作的按钮，当你创建检查运行时，请使用[`actions`对象](/zh/enterprise-server@3.22/rest/checks/runs#create-a-check-run--parameters)。 例如，下面的 `actions` 对象在拉取请求的“检查”选项卡中显示一个按钮，标签为“修复此问题”。 该按钮在检查运行完成后显示。 ```json "actions": [{ "label": "Fix this", "description": "Let us fix that for you", "identifier": "fix_errors" }] ``` 当用户单击该按钮时， GitHub 将 [`check_run.requested_action` Webhook](/zh/enterprise-server@3.22/webhooks/webhook-events-and-payloads#check_run) 发送到应用。 当应用收到 `check_run.requested_action` Webhook 事件时，它可以在 Webhook 有效负载中查找 `requested_action.identifier` 键，以确定单击了哪个按钮，并执行请求的任务。 关于如何使用 REST API 设置请求的操作的详细示例，请参阅“[使用 GitHub 应用构建 CI 检查](/zh/enterprise-server@3.22/apps/creating-github-apps/writing-code-for-a-github-app/building-ci-checks-with-a-github-app)”。 ## 检查数据的保留期 站点管理员可以控制 你的 GitHub Enterprise Server 实例 上检查数据的保留策略。 有关详细信息，请参阅“[配置应用程序](/zh/enterprise-server@3.22/admin/configuring-settings/configuring-user-applications-for-your-enterprise/configuring-applications#enabling-retention-policy-for-checks)”。 要将拉取请求与必需且已存档的检查合并，必须重新运行检查。