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

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

拉取请求 是一个很好的工具，用于促进代码评审和管理存储库中的代码移动。 分支策略 通过在拉取请求过程中强制实施代码质量，方法是确定必须针对每个代码更改执行的要求。 这些策略使团队能够强制实施许多与查看代码和运行自动化生成相关的最佳做法，但许多团队还有其他要求和验证才能在代码上执行。 为了涵盖这些个人和自定义需求，Azure Repos 提供拉取请求状态。 拉取请求状态集成到 PR 工作流中，并允许外部服务通过将简单的成功/失败类型信息与拉取请求相关联，以编程方式注销代码更改。 （可选）在外部服务批准更改之前，可以阻止拉取请求。

先决条件

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

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

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

拉取请求状态

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

• 状态。 以下预定义状态之一：succeeded、、failedpending、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 工具提示中提供。
• 应用 a targetUrl 后，说明将呈现为指向 URL 的链接。

正在更新状态

服务可以通过发布其他状态来更新单个 PR 的 PR 状态，只显示每个唯 context一状态的最新版本。 发布多个状态可帮助用户管理期望。 例如，发布 pending 状态是向用户确认系统已收到事件且正在启动工作的好方法。 使用以下信息 description （如以下示例）可进一步帮助用户了解系统的工作原理：

• “生成排队”
• “正在生成”
• “生成成功”

迭代状态

PR 中的源分支发生更改时，会创建新的“迭代”来跟踪最新更改。 评估代码更改的服务希望在 PR 每次迭代时发布新状态。 将状态发布到 PR 的特定迭代可保证状态仅适用于已评估的代码，并且将来没有更新。

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

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

请参阅 REST API 示例，了解如何 在迭代 和 拉取请求上发布状态。

状态策略

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

像配置其他 分支策略一样配置状态策略。 添加新状态策略时，必须输入状态策略 的名称 和 流派 。 如果之前发布过状态，则可以从列表中选择它;如果是新策略，则可以在格式流派/名称中键入策略的名称。

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

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

策略适用性

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

1. 默认情况下应用 - 策略在创建拉取请求后立即应用。 使用此选项，在发布状态之前 succeeded ，策略不会在拉取请求创建后传递。 可以通过发布状态 notApplicable来标记 PR，从而消除策略要求。

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

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

自定义操作

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

后续步骤

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

• 使用 Node.js创建拉取请求状态服务器
• 使用 Azure Functions 创建自定义分支策略
• 为外部服务配置分支策略