创建自定义部署保护规则

使用 GitHub Apps 通过第三方系统自动保护部署。

谁可以使用此功能？

自定义部署保护规则在所有计划的公共存储库中可用。 要访问专用存储库或内部存储库中的自定义部署保护规则，必须使用 GitHub Enterprise。

本文内容

Note

自定义部署保护规则目前为 beta 版本，可能随时更改。

关于自定义部署保护规则

可以启用自己的自定义保护规则来限制第三方服务的部署。 例如，可以使用 Datadog、Honeycomb 和 ServiceNow 等服务为部署到 GitHub 提供自动审批。

自定义部署保护规则由 GitHub Apps 提供支持，并基于 Webhook 和回调运行。 工作流作业的批准或拒绝基于 deployment_protection_rule Webhook 的使用情况。 有关详细信息，请参阅“Webhook 事件和有效负载”和“批准或拒绝部署”。

创建自定义部署保护规则并将其安装在存储库中后，自定义部署保护规则将自动用于存储库中的所有环境。

使用自定义部署保护规则批准或拒绝部署

可以基于任何外部服务中定义的条件（例如 IT 服务管理 (ITSM) 系统中的已批准票证、依赖项上易受攻击的扫描结果或云资源的稳定运行状况指标）批准或拒绝环境部署。 批准或拒绝部署的决定由集成的第三方应用程序以及在其中定义的限制条件决定。 下面是几个可以为其创建部署保护规则的用例。

  • ITSM 与安全运营：可以通过验证用于验证部署就绪情况的质量、安全性和合规性过程来检查服务就绪情况。
  • 可观测性系统：可以咨询监视或可观测性系统（资产性能管理系统和日志记录聚合器、云资源健康验证系统等），以验证安全性和部署就绪情况。
  • 代码质量和测试工具：可以检查需要部署到环境的 CI 生成的自动测试。

或者，可以为上述任一用例编写自己的保护规则，也可以定义任何自定义逻辑，以安全地批准或拒绝从预生产环境到生产环境的部署。

使用 GitHub Apps 创建自定义部署保护规则

  1. 创建 GitHub App。 有关详细信息，请参阅“注册 GitHub 应用”。 按如下所示配置 GitHub App。

    1. （可选）在“标识和授权用户”下的“回调 URL”文本字段中，输入回调 URL。 有关详细信息，请参阅“关于用户授权回调 URL”。
    2. 在“权限”下，选择“存储库权限”。
    3. 在“操作”右侧，单击下拉菜单，然后选择“访问: 只读”。
      创建新的 GitHub 应用时“存储库权限”部分的屏幕截图。 用于为“操作”配置权限（其中选择了“只读”）的按钮用深橙色矩形突出显示。
    4. 在“部署”右侧，单击下拉菜单，然后选择“访问: 读取和写入”。
      创建新的 GitHub 应用时“存储库权限”部分中“部署”权限设置的屏幕截图。 用于为“部署”配置权限的按钮（其中选择了“只读”权限）的按钮用深橙色矩形突出显示。
    5. 在“订阅事件”下，选择“部署保护规则”。
      创建新的 GitHub 应用时“订阅事件”部分的屏幕截图。 用于订阅部署保护规则事件的复选框用深橙色矩形突出显示。

  2. 在存储库中安装自定义部署保护规则并启用它以供使用。 有关详细信息，请参阅“配置自定义部署保护规则”。

批准或拒绝部署

工作流到达引用了已启用自定义部署保护规则的环境的作业后，GitHub 会将 POST 请求发送到配置的包含 deployment_protection_rule 有效负载的 URL。 可以编写部署保护规则，以自动发送基于 deployment_protection_rule 有效负载批准或拒绝部署的 REST API 请求。 按如下所示配置 REST API 请求。

  1. 验证传入的 POST 请求。 有关详细信息，请参阅“验证 Webhook 交付”。

  2. 使用 JSON Web 令牌以 GitHub App 形式进行身份验证。 有关详细信息，请参阅“验证为 GitHub 应用程序”。

  3. 使用 deployment_protection_rule Webhook 有效负载中的安装 ID 生成安装令牌。 有关详细信息，请参阅“关于使用 GitHub 应用进行身份验证”。

    curl --request POST \
--url "http(s)://HOSTNAME/api/v3/app/installations/INSTALLATION_ID/ACCESS_TOKENS" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer {jwt}" \
--header "Content-Type: application/json" \
--data \
'{ \
   "repository_ids": [321], \
   "permissions": { \
      "deployments": "write" \
   } \
}'

  4. （可选）若要在不对 GitHub 执行任何其他操作的情况下添加状态报告，请向 /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule 发送 POST 请求。 在请求正文中，省略 state。 有关详细信息，请参阅“工作流运行的 REST API 终结点”。 最多可以针对同一部署发布状态报告 10 次。 状态报告支持 Markdown 格式，长度最多为 1024 个字符。

  5. 若要批准或拒绝请求，请向 /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule 发送 POST 请求。 在请求正文中，将 state 属性设置为 approved 或 rejected。 有关详细信息，请参阅“工作流运行的 REST API 终结点”。

  6. （可选）通过向 /repos/OWNER/REPOSITORY_ID/actions/runs/RUN_ID/approvals 发送 GET 请求来请求运行工作流的批准状态。 有关详细信息，请参阅“工作流运行的 REST API 终结点”。

  7. （可选）查看 GitHub 上的部署。 有关详细信息，请参阅“审查部署”。