创建自定义部署保护规则

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

谁可以使用此功能？

自定义部署保护规则在所有计划的公共存储库中可用。要访问私有或内部存储库中的自定义部署保护规则，您必须使用 GitHub Enterprise。有关更多信息，请参阅“GitHub 的计划”。

本文内容

注意

自定义部署保护规则目前处于公开预览阶段，可能会发生更改。

关于自定义部署保护规则

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

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

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

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

可以根据任何外部服务中定义的条件批准或拒绝对环境的部署，例如 IT 服务管理 (ITSM) 系统中的已批准票证、对依赖项的漏洞扫描结果或云资源的稳定运行状况指标。批准或拒绝部署的决定由集成的第三方应用程序及其您在其中定义的限制条件决定。以下是您可以为其创建部署保护规则的一些用例。

  • ITSM 和安全运营：您可以通过验证部署准备情况的质量、安全和合规流程来检查服务准备情况。
  • 可观察性系统：您可以查阅监控或可观察性系统（资产性能管理系统和日志聚合器、云资源健康验证系统等），以验证安全性和部署准备情况。
  • 代码质量和测试工具：您可以检查 CI 构建上的自动化测试，这些测试需要部署到某个环境中。

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

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

  1. 创建一个 GitHub App。有关更多信息，请参阅“注册 GitHub App”。按照以下步骤配置 GitHub App。

    1. 可选地，在“识别和授权用户”下的“回调 URL”文本字段中，输入回调 URL。有关更多信息，请参阅“关于用户授权回调 URL”。
    2. 在“权限”下，选择“存储库权限”。
    3. 在“操作”右侧，单击下拉菜单并选择“访问：只读”。
      Screenshot of the "Repository permissions" section when creating a new GitHub App. The button to configure permissions, with the "read-only" permission selected, for Actions is highlighted by a dark orange rectangle.
    4. 在“部署”右侧，单击下拉菜单并选择“访问：读写”。
      Screenshot of the "Deployments" permission settings in the "Repository permissions" section while creating a new GitHub App. The button to configure permissions, with the "read-only" permission selected, for Deployments is highlighted by a dark orange rectangle.
    5. 在“订阅事件”下，选择“部署保护规则”。
      Screenshot of the "Subscribe to events section" section while creating a new GitHub App. The checkbox to subscribe to the deployment protection rule event is highlighted by a dark orange rectangle.

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

批准或拒绝部署

一旦工作流到达引用启用了自定义部署保护规则的环境的作业，GitHub 会将 POST 请求发送到您配置的包含 deployment_protection_rule 有效负载的 URL。您可以编写部署保护规则来自动发送 REST API 请求，根据 deployment_protection_rule 有效负载批准或拒绝部署。请按以下步骤配置您的 REST API 请求。

  1. 验证传入的 POST 请求。有关更多信息，请参阅“验证来自 GitHub 的有效负载”。

  2. 使用 JSON Web 令牌以 GitHub App 的身份进行身份验证。有关更多信息，请参阅“以 GitHub App 的身份进行身份验证”。

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

    curl --request POST \
--url "https://api.github.com/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 添加状态报告而不采取任何其他操作，请将 POST 请求发送到 /repos/OWNER/REPO/actions/runs/RUN_ID/deployment_protection_rule。在请求正文中，省略 state。有关更多信息，请参阅“工作流运行的 REST API 端点”。您最多可以对同一部署发布 10 次状态报告。状态报告支持 Markdown 格式，并且最多可以包含 1024 个字符。

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

  6. 可选地，通过将 GET 请求发送到 /repos/OWNER/REPOSITORY_ID/actions/runs/RUN_ID/approvals 来请求工作流运行的批准状态。有关更多信息，请参阅“工作流运行的 REST API 端点”。

  7. 可选地，在 GitHub 上查看部署。有关更多信息，请参阅“查看部署”。

在 GitHub Marketplace 中发布自定义部署保护规则

您可以将您的 GitHub App 发布到 GitHub Marketplace，以允许开发人员发现合适的保护规则并在其 GitHub 存储库中安装它。或者，您可以浏览现有的自定义部署保护规则以满足您的需求。有关更多信息，请参阅“关于 GitHub Marketplace 应用”和“在 GitHub Marketplace 上列出应用”。