通过

使用拉取请求状态自定义和扩展拉取请求工作流

  • 项目

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

拉取请求是一种很好的工具，用于促进代码评审以及管理存储库中的代码移动。 分支策略通过建立每次更改代码时都必须执行的要求，在拉取请求过程中加强代码质量。 这些策略使团队能够实施与评审代码和运行自动生成相关的诸多最佳做法，但很多团队对代码有额外的要求并需要对其执行额外的验证。 为了满足这些单独的自定义需求，Azure Repos 提供了拉取请求状态。 拉取请求状态集成到 PR 工作流中，并允许外部服务通过将简单的成功/失败类型信息与拉取请求相关联，以编程方式对代码更改进行签名。 或者，可以在外部服务批准更改之前阻止拉取请求。

集成到 PR 工作流涉及几个不同的概念：

  • 拉取请求状态 - 为服务提供了一种将成功/失败信息与拉取请求相关联的方法。
  • 状态策略 - 提供了一种机制来阻止拉取请求完成，直到拉取请求状态指示成功。
  • 自定义操作 - 提供了一种使用 Azure DevOps Services 扩展来扩展状态菜单的方法。

在本主题中，你将了解拉取请求状态，以及如何使用它们集成到 PR 工作流中。

拉取请求状态

拉取请求状态为服务提供了一种使用状态 API 将简单的成功/失败类型信息与拉取请求相关联的方法。 状态由四个关键数据部分组成：

  • 状态。 以下预定义状态之一：succeeded、failed、pending、notSet、notApplicable 或 error。
  • 说明。 向最终用户描述状态的字符串。
  • 上下文。 状态的名称 - 通常描述发布状态的实体。
  • URL。 一个链接，用户可通过该链接获取特定于状态的详细信息。

从本质上讲，状态是用户或服务发布其对拉取请求的评估并提供类似于以下问题的问题答案的方式：

  • 更改是否满足要求？
  • 在哪里可以详细了解需要执行哪些操作才能满足要求？

我们来看一个示例。 考虑在项目中生成所有代码更改所需的 CI 服务。 当该服务评估拉取请求中的更改时，它需要回发生成和测试的结果。 对于通过生成的更改，PR 上可能会发布如下所示的状态：

{
    "state": "succeeded",
    "description": "CI build succeeded",
    "context": {
        "name": "my-ci-system",
        "genre": "continuous-integration"
    },
    "targetUrl": "http://contoso.com/CI/builds/1"
}

此状态将在“PR 详细信息”视图中显示给最终用户：

拉取请求状态

  • state 通过图标显示给用户（绿色钩号表示 succeeded，红色 X 表示 failed，时钟表示 pending，红色 ! 表示 error）。
  • description 显示在图标旁边，context 在工具提示中提供。
  • 应用 targetUrl 时，说明将呈现为指向 URL 的链接。

正在更新状态

服务可以通过发布其他状态来更新单个 PR 的 PR 状态，仅针对每个唯一 context 显示最新状态。 发布多个状态有助于用户管理预期。 例如，发布 pending 状态是向用户确认系统已收到事件并正在开始工作的好方法。 使用以下示例等信息性 description 可以进一步帮助用户了解系统的工作原理：

  • “生成已排队”
  • “生成正在进行中”
  • “生成已成功”

迭代状态

当 PR 中的源分支发生更改时，将创建新的“迭代”来跟踪最新更改。 评估代码更改的服务将需要在 PR 每次迭代时发布新状态。 将状态发布到 PR 的特定迭代可以保证该状态仅适用于已评估的代码，而不适用于将来的更新。

注意

如果创建的 PR 包含超过 100,000 个修改过的文件，则出于性能和稳定性原因，该 PR 将不支持迭代。 这意味着将包含对此类 PR 的任何其他更改，但不会为该更改创建新的迭代。 此外，任何为不存在的迭代创建状态的尝试都将返回错误。

相反，如果发布的状态适用于整个 PR（独立于代码），则可能不需要发布到迭代。 例如，检查作者（不可变的 PR 属性）是否属于特定的组只需要评估一次，无需迭代状态。

配置状态策略时，如果使用迭代状态，则应将“重置条件”设置为“每当有新更改时重置状态”。 这进一步保证了 PR 在最新迭代的状态为 succeeded 之前无法合并。

状态策略重置条件

有关在迭代上和在拉取请求上发布状态的信息，请参阅 REST API 示例。

状态策略

单独使用状态，可以在 PR 体验中向用户提供来自外部服务的详细信息。 有时，共享有关 PR 的信息是必要的，但在其他情况下，在满足要求之前，应阻止 PR 合并。 与现成策略一样，状态策略为外部服务提供了一种在满足要求之前阻止 PR 完成的方法。 如果需要该策略，该策略必须传递才能完成拉取请求。 如果该策略是可选的，则它只是信息性策略，并且无需状态 succeeded 即可完成拉取请求。

状态策略的配置与其他分支策略一样。 添加新状态策略时，必须输入状态策略的名称和类型。 如果之前已发布状态，则可以从列表中选取它；如果它是新策略，则可以按“类型/名称”的格式键入该策略的名称。

状态策略

指定状态策略时，它要求存在具有与所选名称匹配的 context 的 succeeded 状态，以便此策略传递。

还可以选择“授权帐户”，以要求特定帐户有权发布将批准该策略的状态。

策略适用性

“策略适用性”选项确定此策略是在创建拉取请求后立即应用，还是仅在第一个状态发布到拉取请求后应用。

策略适用性

  1. 默认应用 - 在创建拉取请求后立即应用策略。 使用此选项时，在发布 succeeded 状态之前，策略不会在创建拉取请求后传递。 可以通过发布状态 notApplicable 来将 PR 标记为不受策略限制，此操作将删除策略要求。

  2. 条件 - 在将第一个状态发布到拉取请求之后才应用策略。

这些选项可以一起用于创建一套动态策略。 在评估 PR 的适用策略时，可以将顶级“业务流程”策略设置为默认应用。 然后，在确定要应用其他条件策略时（可能基于特定的生成输出），可以发布状态以使这些策略成为必需策略。 此业务流程策略可以在完成评估时标记为 succeeded，也可以标记为 notApplicable 以向 PR 指示该策略不适用。

自定义操作

除了可以触发服务更新 PR 状态的预定义服务挂钩事件外，还可以通过使用 Azure DevOps Services 扩展来扩展状态菜单，为最终用户提供触发操作。 例如，如果状态对应于最终用户可以重启的测试运行，则可以在状态菜单中设置“重启”菜单项，以触发测试运行。 若要添加状态菜单，需要使用贡献模型。 有关详细信息，请参阅 Azure DevOps 扩展示例。

“状态”菜单

后续步骤

详细了解 PR 状态 API 并查看操作指南：