通过

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

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

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

先决条件

类别 要求
项目访问权限 项目的成员。
权限 - 查看私有项目中的代码：至少 基本 访问权限。
- 克隆或贡献代码到私有项目中：必须是“贡献者”安全组的成员或拥有项目中的相应权限。
- 设置分支或存储库权限： 管理权限 是分支或存储库的权限。
- 更改默认分支： 编辑策略 是存储库的权限。
- 导入存储库： 项目管理员 安全组的成员或 Git 项目级 “创建存储库 ”权限设置为 “允许”。 有关详细信息，请参阅 “设置 Git 存储库权限”。
Services 已启用存储库。
工具 可选。 使用 az repos 命令： Azure DevOps CLI。

注释

在公共项目中，具有 利益干系人 访问权限的用户具有对 Azure Repos 的完全访问权限，包括查看、克隆和参与代码。

类别 要求
项目访问权限 项目的成员。
权限 - 查看代码：至少 基本 访问权限。
- 克隆或贡献代码：参与者 安全组成员或具备项目中的相应权限。
Services 已启用存储库。

集成到 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绿色勾、failed红色 X、pending钟形图标和error红色感叹号）。
  • description 显示在图标旁，context 可在工具提示中查看。
  • 应用 a targetUrl 后，说明将呈现为指向 URL 的链接。

正在更新状态

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

  • “生成排队”
  • 正在构建中
  • “生成成功”

迭代状态

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

注释

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

相反，如果发布的状态适用于整个 PR，而不依赖于代码，那么发布到迭代可能显得多余。 例如，检查作者（不可变 PR 属性）是否属于特定组只需评估一次，并且不需要迭代状态。

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

状态策略重置条件

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

状态策略

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

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

状态策略

当指定状态策略时，要求具有succeededcontext状态，并且与所选名称匹配，以确保该策略能够通过。

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

策略适用性

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

策略适用性

  1. 默认情况下应用 - 策略在创建拉取请求后立即应用。 选择此选项后，策略在拉取请求创建后不会通过，直到发布succeeded状态。 可以通过状态设置为 notApplicable来标记 PR 为豁免，从而解除策略要求。

  2. 条件 - 策略不会生效，直到第一个状态被发布到拉取请求。

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

自定义操作

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

“状态”菜单

后续步骤

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

  • Last updated on