Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022
拉取请求 是一个很好的工具,用于促进代码评审和管理存储库中的代码移动。 分支策略 在拉取请求过程中强制代码质量,通过设定每次代码更改必须满足的要求。 这些策略使团队能够强制实施许多与查看代码和运行自动化生成相关的最佳做法,但许多团队还有其他要求和验证才能在代码上执行。 为了涵盖这些个人和自定义需求,Azure Repos 提供拉取请求状态。 拉取请求状态集成到 PR 工作流中,并允许外部服务通过将简单的成功/失败类型信息与拉取请求相关联,以编程方式注销代码更改。 (可选)在外部服务批准更改之前,可以阻止拉取请求。
先决条件
| 类别 | 要求 |
|---|---|
| 项目访问权限 | 项目的成员。 |
| 权限 | - 查看私有项目中的代码:至少 基本 访问权限。 - 克隆或贡献私有项目中的代码:参与者 安全组的成员或项目中的相应的权限。 - 设置分支或存储库权限: 管理 分支或存储库的权限。 - 设置分支策略、状态检查或更改默认分支:编辑存储库或分支的策略权限,或Project管理员安全组中的成员身份。 - 导入存储库: 项目管理员 安全组的成员或 Git 项目级 “创建存储库 ”权限设置为 “允许”。 有关详细信息,请参阅 “设置 Git 存储库权限”。 |
| Services | 已启用存储库。 |
| 工具 | 可选。 使用 az repos 命令: Azure DevOps CLI。 |
集成到 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 包含超过 100,000 个修改的文件,则出于性能和稳定性原因,PR 不支持迭代。 这意味着将包含对此类 PR 进行的任何其他更改,但不会为该更改创建新的迭代。 此外,任何尝试为不存在的迭代创建状态都将返回错误。
相反,如果发布的状态适用于整个 PR(独立于代码),则可能不需要发布到迭代。 例如,检查作者(不可变 PR 属性)是否属于特定组只需评估一次,并且不需要迭代状态。
配置状态策略时,如果使用迭代状态,则每当有新更改时,“重置条件”应设置为“重置”状态。
这进一步保证了 PR 在最新迭代的状态为 succeeded 之前无法合并。
请参阅 REST API 示例,了解如何 在迭代 和 拉取请求上发布状态。
状态策略
单独使用状态,可以在 PR 体验中向用户提供来自外部服务的详细信息。
有时,共享有关 PR 的信息是必需的,但在其他情况下,应阻止 PR 合并,直到满足要求。
与现成策略一样,状态策略为外部服务提供了一种在满足要求之前阻止 PR 完成的方法。 如果需要该策略,该策略必须传递才能完成拉取请求。 如果该策略是可选的,则它只是信息性策略,并且无需状态 succeeded 即可完成拉取请求。
像配置其他 分支策略一样配置状态策略。 添加新状态策略时,必须输入状态策略 的名称 和 流派 。 如果之前发布过状态,则可以从列表中选择它;如果是新策略,则可以在格式流派/名称中键入策略的名称。
指定状态策略时,它要求存在具有与所选名称匹配的 context 的 succeeded 状态,以便此策略传递。
还可以选择 授权帐户 以要求特定帐户有权发布将批准策略的状态。
策略适用性
策略适用性选项确定在创建拉取请求后是否立即应用此策略,还是仅在将第一个状态发布到拉取请求后应用策略。
默认情况下应用 - 策略在创建拉取请求后立即应用。 使用此选项时,在发布
succeeded状态之前,策略不会在创建拉取请求后传递。 可以通过状态设置为notApplicable来标记 PR 为豁免,从而解除策略要求。条件 - 策略不会生效,直到第一个状态被发布到拉取请求。
这些选项一起可用于创建一套动态策略。
在评估 PR 的适用策略时,可以将顶级“业务流程”策略设置为默认应用。
然后,在确定要应用其他条件策略时(可能基于特定的生成输出),可以发布状态以使这些策略成为必需策略。
此编排策略可以在评估完成后标记为 succeeded,也可以标记为 notApplicable 指示 PR 该策略不适用。
自定义操作
除了可以触发服务更新 PR 状态的预定义服务挂钩事件外,还可以使用 Azure DevOps Services 扩展 来扩展状态菜单,以便为最终用户提供触发器作。 例如,如果状态对应于最终用户可以重启的测试运行,则可以将 “重启” 菜单项添加到状态菜单中,以便触发测试运行。 若要添加状态菜单,需要使用 贡献模型。 有关详细信息,请参阅 Azure DevOps 扩展示例。
后续步骤
详细了解PR 状态 API并查看操作指南: