设置和管理分支策略

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

使用分支策略通过要求在更改合并之前进行拉取请求、审查者、生成和其他检查来保护重要分支。 本文介绍如何在 Azure DevOps Web 门户和 Azure DevOps CLI 中配置和管理分支策略。 有关可用分支策略和分支指南的摘要,请参阅 关于分支和分支策略。

有关涵盖分支策略、存储库访问控制、提交签名和实际实现方案的综合安全指南,请参阅 安全存储库和拉取请求。

无法删除配置了所需策略的分支,所有更改都必须通过拉取请求(PR)。

小窍门

可以在本文后面使用 AI 来帮助完成此任务,或参阅启用 Azure DevOps MCP Server 的 AI 帮助以开始使用。

先决条件

Requirement 详细信息
Permissions 成为Project管理员安全组的成员,或者具有存储库级别的编辑策略权限。 有关详细信息,请参阅设置 Git 存储库权限。
Azure DevOps CLI 设置(可选) 若要使用 Azure DevOps CLI az repos policy 命令,请完成 Azure DevOps CLI 入门。
CLI 的存储库目标(可选) 在 CLI 中创建或更新策略之前,请通过运行 az repos list来标识存储库 ID。 若要避免重复 --org 和 --project,请使用 az devops configure --defaults 设置默认值。
策略依赖项 在配置 生成验证之前,请准备好生成管道。 在配置 状态检查之前,请确保外部服务或内置集成已发布拉取请求状态。
AI 协助设置(可选) 若要在 AZURE DEVOPS MCP Server 中使用 AI 帮助,请使用Azure DevOps服务,在 AI 助手中启用代理模式,并安装 Node.js 20.0+。 有关详细信息,请参阅使用 Azure DevOps MCP Server 启用 AI 助手。
Requirement 详细信息
Permissions 成为Project管理员安全组的成员,或者具有存储库级别的编辑策略权限。 有关详细信息,请参阅设置 Git 存储库权限。

打开分支策略设置

若要在 Web 门户中打开分支策略设置,请执行以下操作:

  1. 选择存储库>分支。
  2. 查找要管理的分支。
  3. 选择分支旁边的 “更多选项” 图标,然后选择 “分支策略”。

显示“分支”菜单项的屏幕截图。

还可以从项目设置>存储库>策略>分支策略><分支名称>中的“分支策略设置”打开。

具有策略的分支会显示一个策略图标。 选择图标直接转到分支的策略设置。

可以在 “搜索分支名称 ”框中浏览列表或搜索分支。

显示“从上下文菜单打开分支策略”的屏幕截图。

在分支的设置页上配置策略。 使用以下部分来启用各项策略或更新现有策略。

设置最低审阅者策略

在拉取请求可以完成之前,要求最少数量的审查者批准。

要设置策略,请在“分支策略”下,将“需要最少数量的审阅者”设置为“开”。 输入所需的审阅者数,并选择以下任一选项:

显示启用“需要代码评审”策略的屏幕截图。

  • 选择 允许请求者批准自己的更改 以允许 PR 的创建者对其审批进行投票。 否则,创建者仍然可以在该 PR 上投 “批准”票,但其投票不计入所需的最低审阅人数。

  • 选择“禁止近期的推送者审批自己的更改”以强制实施职责分离。 默认情况下,任何对源分支具有推送权限的人都可以添加提交并对 PR 审批进行投票。 选择此选项意味着最近推送者的投票不计算在内,即便他们通常可以批准自己的更改。

  • 选择“即使某些审阅者投票等待或拒绝,仍允许完成”,以便即使某些审阅者投票反对 PR 仍能完成。 必须由至少规定数量的审阅者进行批准。

  • 在“推送新更改时”选项下:
    • 选择“每次迭代至少需要获得一个批准”,以要求对上次源分支更改进行至少一次审批投票。 用户的批准不会计入该用户推送的任何先前未经批准的迭代。 因此,需要由另一个用户对上次迭代进行批准。 Azure DevOps Server 2022.1 及更高版本提供“每次迭代至少需要获得一个批准”功能。
    • 选择“最后一次迭代至少需要一个审批投票”,以确保对最后一次源分支变更至少需要一个审批投票。
    • 选择“重置所有审批投票(不重置“拒绝”或“等待”投票)”,以便在源分支每次发生更改时删除所有审批投票,但保留拒绝或等待投票。
    • 选择“重置所有代码审阅者投票”,以便每当源分支发生更改时删除所有审阅者投票,包括批准、拒绝或等待的投票。

如果所有其他策略都通过,则创建者可以在所需数量的审阅者批准 PR 后完成该 PR。

选择链接的工作项

对于工作项管理跟踪,可以要求在 PR 和工作项之间创建关联。 链接工作项为更改提供更多上下文,并确保更新通过工作项跟踪流程。

要设置策略,请在“分支策略”下,将“检查链接的工作项”设置为“开”。 此设置要求将工作项链接到 PR,以便 PR 合并。 将设置设为“可选”,以便在没有链接的工作项时发出警告,但允许完成拉取请求。

拉取请求中需要关联工作项的屏幕截图。

要求评论解决

“检查注释解决情况”策略检查是否已解决所有 PR 注释。

将 “检查评论解决状态” 设置为 “开启”,以便为您的分支配置评论解决策略。 然后选择是将策略设为“必需”还是“可选”。

“检查评论分辨率”的屏幕截图。

有关使用拉取请求注释的详细信息,请参阅 “查看拉取请求”。

限制合并类型

Azure Repos支持多个合并策略,默认情况下,它允许所有这些策略。 为了保持一致的分支历史记录,对 PR 完成强制执行合并策略。

将 “限制合并类型 ”设置为 “打开 ”以限制存储库中允许的合并类型。

限制合并类型的屏幕截图。

  • 基本合并(无快进)在目标中创建一个合并提交,其父级是目标和源分支。
  • Squash 合并在目标分支中创建具有单个提交的线性历史记录,其中包含来自源分支的更改。 详细了解压缩合并及其如何影响分支历史记录。
  • 变基和快进通过在不合并提交的情况下将源提交重播到目标分支来创建线性历史记录。
  • 通过合并提交变基可将源提交重播至目标,并创建合并提交。

设置构建验证

设置一项策略,要求 PR 更改在 PR 可以完成之前成功生成。 生成策略可减少中断并保持测试结果通过。 即使在开发分支上使用持续集成 (CI) 来及早发现问题,生成策略也会有所帮助。

将策略触发器设置为 “自动”时,生成验证策略会在创建新 PR 时对新生成进行排队,或者将更改推送到面向分支的现有 PR。 如果将策略触发器设置为“手动”,用户必须自己将生成排队。 在这两种情况下,策略都会评估生成结果以确定 PR 是否可以完成。

重要

在指定生成验证策略之前,请创建生成管道。 如果没有管道,请参阅创建生成管道。 选择与项目类型匹配的生成类型。

添加生成验证策略

  1. 选择“生成验证”旁边的 + 按钮。

    显示“构建验证”旁边的“添加”按钮的屏幕截图。

  2. 填写“设置生成策略”窗体:

    “生成策略设置”的屏幕截图。

    • 选择“生成管道”。

    • (可选)设置一个路径筛选器。 详细了解分支策略中的路径筛选器。

    • 在“触发器”下,选择“自动(每当源分支更新时)”或“手动”。

    • 在“策略要求”下,选择“必需”或“可选”。 如果选择“必需”,则生成必须成功完成才能完成 PR。 选择“可选”可在生成失败时发送通知,但仍允许 PR 完成。

    • 设置生成过期时间,以确保对受保护分支的更新不会中断打开的 PR 的更改。

      • 更新<分支名称>后立即:每当分支更新时,此选项将 PR 生成策略状态设置为失败。 对于自动策略,它还会将新的构建加入队列。 此设置可确保即使受保护分支更改,PR 更改也能成功生成。

        此选项最适合重要分支几乎没有更改的团队。 使用繁忙开发分支的团队可能会发现,每次分支更新时等待生成都会造成中断。

      • 如果<分支名称>已更新,则在 <n> 小时后:如果传递的生成早于输入的阈值,则当受保护的分支更新时,此选项将使当前策略状态过期。 此选项是在受保护分支更新时始终或从不需要生成之间的折衷。 当受保护的分支频繁更新时,此选项可以减少构建数。

      • 从不:对受保护分支的更新不会更改策略状态。 此值可减少生成数,但在完成最近未更新的 PR 时可能会导致问题。 对于手动策略,源分支更新也不会使构建过期。 对于自动策略,源分支更新始终会导致生成失效。

        对于在源分支更新时过期的手动策略,请选择在 <n> 小时后(如果<分支名称>已更新),并输入最长持续时间 8,784 小时(366 天)。 目标分支更新在该持续时间内不会使生成过期。

    • 为此生成策略输入可选的显示名称。 此名称标识“分支策略”页上的策略。 如果未指定显示名称,则策略将使用生成管道名称。

  3. 选择“保存”。

当新的验证生成成功时,策略状态会更新。

如果具有“更新<分支名称>后立即”或“如果<分支名称>已更新,则在 <n> 小时后”生成策略,则策略状态会随受保护分支更新而更新,前提是先前的生成不再有效。

要求状态检查

外部服务可以使用 PR 状态 API 将详细状态发布到 PR。 附加服务的分支策略使这些外部服务能够参与 PR 工作流和建立策略要求。

“要求外部服务批准”的屏幕截图。

若要配置状态检查策略,请执行以下操作:

  1. 确保该服务可以将拉取请求状态发布到 Azure Repos。
  2. 在 分支策略的 “状态检查”下,选择 +。
  3. 在“要检查的状态”中,从列表中选择已发布的检查。 如果服务尚未发布状态,请直接键入 genre/name 值。
  4. 将 策略要求 设置为 “必需 ”或 “可选”。
  5. (可选)配置 授权标识、 重置条件、 策略适用性和 路径筛选器。
    • 如果策略应在创建拉取请求后立即应用,请使用默认应用。
    • 如果策略仅在发布第一个状态后应用,请使用 条件 。
  6. 创建或更新一个以该分支为目标的拉取请求,并确认该策略显示在 PR 的 策略 部分中。

有关内置 Azure DevOps Services 检查及其 genre/name 标识符,请参阅可用的拉取请求状态检查。 有关外部服务设置的完整演练,请参阅 为外部服务配置分支策略。

如果新集成尚未显示在下拉列表中,请从服务发布一次状态,然后添加策略或直接键入 genre/name 值。

自动包括审阅者

可以自动为更改特定目录和文件中的文件的拉取请求添加审阅者,或者为存储库中的所有拉取请求添加审阅者。

  1. 选择“自动包含的审阅者”旁边的 + 按钮。

    显示“添加所需审阅者”的屏幕截图。

  2. 请填写“添加新审阅者策略”页面。

    显示“添加新审阅者策略”屏幕的屏幕截图。

    • 将人员和组添加到“审阅者”。

    • 如果要自动添加审阅者,但不需要他们的批准即可完成拉取请求,请选择“可选”。

      或者,如果在满足以下条件后才能完成拉取请求,请选择“必需”:

      • 每位被添加为审阅者的人都会审批更改。
      • 添加为审阅者的每个组中至少有一人批准更改。
      • 如果只需要一个组,则由你指定的最小成员数批准更改。
    • 请指定需要自动包含评审人的文件和文件夹。 将此字段留空以要求审阅者处理分支中的所有拉取请求。

    • 如果拉取请求所有者可以投票批准自己的拉取请求来满足此策略,请选择“允许请求者批准自己的更改”。

    • 可以指定拉取请求中显示的活动源消息。

  3. 选择“保存”。

允许在需要时绕过策略

在某些情况下,可能需要绕过策略要求。 通过绕过权限,可以直接将更改推送到分支,或完成不符合分支策略的拉取请求。 你可以向用户或组授予绕过权限,并将这些权限限定为整个项目、存储库或单个分支。

以下两种权限允许用户以不同方式绕过分支策略:

  • 完成拉取请求时的绕过策略仅会应用于拉取请求完成。 即使拉取请求不符合策略,具有此权限的用户也可以完成拉取请求。

  • 推送时绕过策略 - 适用于来自本地存储库的推送和在 Web 上进行的编辑。 具有此权限的用户可以将更改直接推送到受保护的分支,而无需满足策略要求。

显示绕过策略实施权限的屏幕截图。

有关管理这些权限的详细信息,请参阅 Git 权限。

重要

授予绕过策略的权限时要小心,尤其是在存储库和项目级别。 策略是安全且合规的源代码管理的基石。

将路径筛选器与分支策略配合使用

多个分支策略支持路径筛选器。 如果设置路径筛选器,则策略仅适用于与筛选器匹配的文件。 将此字段留空,将策略应用于分支中的所有文件。

可以指定绝对路径(路径必须以 / 或通配符开头)和通配符。 示例:

  • /WebApp/Models/Data.cs
  • /WebApp/*
  • */Models/Data.cs
  • *.cs

可以通过用作 ; 分隔符来指定多个路径。 示例:

  • /WebApp/Models/Data.cs;/ClientApp/Models/Data.cs

如果在路径前加上 ! 前缀,那么即使这些路径原本会被包含,也会被排除。 示例:

  • /WebApp/*;!/WebApp/Tests/* 包括 /WebApp 中的所有文件,/WebApp/Tests 中的文件除外
  • !/WebApp/Tests/* 不指定任何文件,因为一开始不包含任何内容

筛选器的顺序非常重要。 从左到右应用筛选器。

排查分支策略问题

能否直接将更改推送到已设置分支策略的分支?

除非拥有绕过分支策略的权限,否则无法将更改直接推送到具有必需分支策略的分支。 只能通过 拉取请求对这些分支进行更改。 如果没有必需的分支策略,可以将更改直接推送到具有可选分支策略的分支。

什么是自动完成?

已为拉取请求配置分支策略的分支会显示“设置自动完成”按钮。 选择此选项可将拉取请求设置为自动完成,并在其满足所有策略后自动完成。 当预计更改不会出现任何问题时,自动完成功能非常有用。

何时检查分支策略条件?

当拉取请求所有者推送更改和审阅者投票时,服务器将重新评估分支策略。 如果策略触发构建,则构建状态会被设置为等待,直到构建完成。

能否在分支策略中使用 XAML 生成定义?

否,不能在分支策略中使用 XAML 生成定义。

对于所需的代码审阅者,可以使用哪些通配符?

单个星号 * 匹配任意数量的字符,包括正斜杠 / 和反斜杠 \。 问号 ? 匹配任何单个字符。

示例:

  • *.sql 匹配所有扩展名为 .sql 的文件。
  • /ConsoleApplication/* 匹配名为 ConsoleApplication 的文件夹下的所有文件。
  • /.gitattributes 匹配存储库根目录中的 .gitattributes* 文件。
  • */.gitignore 匹配存储库中的任何 .gitignore 文件。

所需的代码审阅者路径是否区分大小写?

否,分支策略不区分大小写。

如何将多个用户配置为所需的审阅者,但只需要其中一个用户批准?

可以将用户添加到组,然后将该组添加为审阅者。 然后,组的任何成员都可以批准以满足策略要求。

我具有绕过策略权限。 为什么在拉取请求状态中仍会看到策略失败?

系统始终会针对拉取请求中的更改评估已配置的策略。 对于具有绕过策略权限的用户,报告的策略状态仅为公告。 如果具有绕过权限的用户批准,则失败状态不会阻止拉取请求完成。

为什么将“允许请求者批准自己的更改”设置启用后,我仍无法完成自己的拉取请求?

“需要最少数量的审阅者”策略和“自动包含审阅者”策略都具有“允许请求者批准自己的更改”的选项。 在每个策略中,设置仅适用于该策略。 设置不会影响其他策略。

例如,您的合并请求设置了以下策略:

  • 需要最少数量的审阅者 - 需要至少一个审阅者。
  • 自动包含的审阅者需要你或你作为审阅者加入的团队。
  • 自动包含的审阅者已启用允许请求者批准自己的更改。
  • 需要最少数量的审阅者未启用允许请求者批准自己的更改。

在此情况下,您的批准满足自动包括的审阅者,但不满足需要的最少审阅者数量,因此您无法完成此拉取请求。

其他策略可能会阻止你批准自己的更改,即使 设置了“允许请求者批准自己的更改 ”。 例如,禁止最近的推送者批准他们自己的更改。

如果路径筛选器不是以 / 或通配符开头,会发生什么情况?

路径筛选器中,任何不是以 / 或通配符开头的路径都不会生效。 路径筛选器的计算结果与未指定路径一样。 这样的路径无法与绝对文件路径开头的 / 匹配。

使用 AI 配置和管理分支策略

如果配置 Azure DevOps MCP 服务器,则可以使用自然语言在 Azure DevOps Services 中更新分支策略之前收集存储库、分支、拉取请求和生成上下文。

Azure DevOps MCP 服务器需要Azure DevOps服务、AI 助手中的代理模式和 Node.js 20.0+。 当前 MCP 文档不描述直接分支策略读取或写入操作,因此请使用 Azure DevOps Web 门户或 Azure DevOps CLI 来创建和更新策略。

任务 示例提示
列出存储库中的分支 List the branches in repo <Contoso.Web> in project <Contoso>
在收紧策略之前审查拉取请求 What pull requests require my review in project <Contoso>?
查看拉取请求和关联的工作项 Get details for pull request <67> and its linked work items in project <Contoso>
在将构建验证设为必需之前检查构建状态 Get the latest build status for pipeline <Contoso-CI> in project <Contoso>

注释

如果你使用 Visual Studio Code,代理模式对于在更新分支策略之前收集所需的项目上下文尤其有帮助。