Edit

Set and manage branch policies

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

Use branch policies to protect important branches by requiring pull requests, reviewers, builds, and other checks before changes merge. This article shows how to configure and manage branch policies in the Azure DevOps web portal and Azure DevOps CLI. For a summary of available branch policies and branching guidance, see About branches and branch policies.

For a comprehensive security guide covering branch policies, repository access control, commit signing, and real-world implementation scenarios, see Secure repositories and pull requests.

You can't delete a branch with required policies configured, and all changes must go through pull requests (PRs).

Tip

You can use AI to help with this task later in this article, or see Enable AI assistance with Azure DevOps MCP Server to get started.

Prerequisites

Requirement Details
Permissions Be a member of the Project Administrators security group, or have repository-level Edit policies permissions. For more information, see Set Git repository permissions.
Azure DevOps CLI setup (optional) To use Azure DevOps CLI az repos policy commands, complete Get started with Azure DevOps CLI.
Repository targeting for CLI (optional) Before you create or update policies in CLI, identify the repository ID by running az repos list. To avoid repeating --org and --project, set defaults with az devops configure --defaults.
Policy dependencies Before you configure Build validation, have a build pipeline ready. Before you configure Status checks, make sure the external service or built-in integration can already post pull request status.
AI assistance setup (optional) To use AI assistance with Azure DevOps MCP Server, use Azure DevOps Services, enable agent mode in your AI assistant, and install Node.js 20.0+. For more information, see Enable AI assistance with Azure DevOps MCP Server.
Requirement Details
Permissions Be a member of the Project Administrators security group, or have repository-level Edit policies permissions. For more information, see Set Git repository permissions.

Open branch policy settings

To open branch policy settings in the web portal:

  1. Select Repos > Branches.
  2. Find the branch that you want to manage.
  3. Select the More options icon next to the branch, and then select Branch policies.

Screenshot that shows the Branches menu item.

You can also open branch policy settings from Project settings > Repository > Policies > Branch Policies > <Branch name>.

Branches that have policies display a policy icon. Select the icon to go directly to the branch's policy settings.

You can browse the list or search for the branch in the Search branch name box.

Screenshot that shows Open the branch policies from the context menu.

Configure policies on the branch's settings page. Use the following sections to turn each policy on or update an existing policy.

Set a minimum reviewer policy

Require approval from a minimum number of reviewers before a pull request can complete.

To set the policy, under Branch Policies, set Require a minimum number of reviewers to On. Enter the required number of reviewers, and select any of the following options:

Screenshot that shows the Enable the Require Code Reviews policy.

  • Select Allow requestors to approve their own changes to allow a PR's creator to vote on its approval. Otherwise, the creator can still vote Approve on the PR, but their vote doesn't count toward the minimum number of reviewers.

  • Select Prohibit the most recent pusher from approving their own changes to enforce segregation of duties. By default, anyone with push permission on the source branch can both add commits and vote on PR approval. Selecting this option means the most recent pusher's vote doesn't count, even if they can ordinarily approve their own changes.

  • Select Allow completion even if some reviewers vote to wait or reject to allow PR completion even if some reviewers vote against approval. The minimum number of reviewers must still approve.

  • Under When new changes are pushed:
    • Select Require at least one approval on every iteration to require at least one approval vote for the last source branch change. The user's approval isn't counted against any previous unapproved iteration pushed by that user. As a result, another approval on the last iteration is required to be done by another user. Require at least one approval on every iteration is available in Azure DevOps Server 2022.1 and higher.
    • Select Require at least one approval on the last iteration to require at least one approval vote for the last source branch change.
    • Select Reset all approval votes (does not reset votes to reject or wait) to remove all approval votes, but keep votes to reject or wait, whenever the source branch changes.
    • Select Reset all code reviewer votes to remove all reviewer votes whenever the source branch changes, including votes to approve, reject, or wait.

If all other policies pass, the creator can complete the PR when the required number of reviewers approve it.

Require linked work items

For work item management tracking, you can require associations between PRs and work items. Linking work items provides more context for changes, and ensures that updates go through your work item tracking process.

To set the policy, under Branch Policies, set Check for linked work items to On. This setting requires that work items be linked to a PR for the PR to merge. Make the setting Optional to warn when there are no linked work items, but allow completion of the pull request.

Screenshot of requiring linked work items in pull requests.

Require comment resolution

The Check for comment resolution policy checks whether all PR comments are resolved.

Set Check for comment resolution to On to configure a comment resolution policy for your branch. Then select whether to make the policy Required or Optional.

Screenshot of Check for comment resolution.

For more information about working with pull request comments, see Review pull requests.

Limit merge types

Azure Repos supports several merge strategies, and by default, it allows all of them. To keep a consistent branch history, enforce a merge strategy for PR completion.

Set Limit merge types to On to limit which merge types are allowed in your repo.

Screenshot of Limit merge types.

  • Basic merge (no fast-forward) creates a merge commit in the target whose parents are the target and source branches.
  • Squash merge creates a linear history with a single commit in the target branch that includes the changes from the source branch. Learn more about squash merging and how it affects branch history.
  • Rebase and fast-forward creates a linear history by replaying source commits onto the target branch with no merge commit.
  • Rebase with merge commit replays the source commits onto the target and also creates a merge commit.

Set build validation

Set a policy that requires PR changes to build successfully before the PR can complete. Build policies reduce breaks and keep your test results passing. Build policies help even if you're using continuous integration (CI) on your development branches to catch problems early.

When you set the policy trigger to Automatic, a build validation policy queues a new build when you create a new PR or push changes to an existing PR that targets the branch. If you set the policy trigger to Manual, users must queue the build themselves. In both cases, the policy evaluates the build results to determine whether the PR can be completed.

Important

Before specifying a build validation policy, create a build pipeline. If you don't have a pipeline, see Create a build pipeline. Choose the type of build that matches your project type.

To add a build validation policy

  1. Select the + button next to Build validation.

    Screenshot that shows the Add button next to Build validation.

  2. Fill out the Set build policy form:

    Screenshot of Build policy settings.

    • Select the Build pipeline.

  • Optionally set a Path filter. Learn more about path filters in branch policies.

  • Under Trigger, select Automatic (whenever the source branch is updated) or Manual.

  • Under Policy requirement, select Required or Optional. If you choose Required, builds must complete successfully to complete PRs. Choose Optional to provide a notification of the build failure but still allow PRs to complete.

  • Set a build expiration to make sure updates to your protected branch don't break changes for open PRs.

    • Immediately when <branch name> is updated: This option sets PR build policy status to failed whenever the branch is updated, and requeues a build. This setting ensures that the PR changes build successfully even if the protected branch changes.

      This option is best for teams whose important branches have few changes. Teams working in busy development branches might find it disruptive to wait for a build every time the branch updates.

    • After <n> hours if <branch name> has been updated: This option expires the current policy status when the protected branch updates if the passing build is older than the threshold you enter. This option is a compromise between always or never requiring a build when the protected branch updates. This choice reduces the number of builds when your protected branch has frequent updates.

    • Never: Updates to the protected branch don't change the policy status. This value reduces the number of builds, but can cause problems when completing PRs that weren't updated recently.

  • Enter an optional Display name for this build policy. This name identifies the policy on the Branch policies page. If you don't specify a display name, the policy uses the build pipeline name.

  1. Select Save.

When the PR owner pushes changes that build successfully, the policy status updates.

If you have an Immediately when <branch name> is updated or After <n> hours if <branch name> has been updated build policy, the policy status updates when the protected branch updates, if the previous build is no longer valid.

Require status checks

External services can use the PR Status API to post detailed status to your PRs. The branch policy for additional services enables those external services to participate in the PR workflow and establish policy requirements.

Screenshot of Require external services to approve.

To configure a status check policy:

  1. Make sure the service can post pull request status to Azure Repos.
  2. In Branch policies, under Status checks, select +.
  3. In Status to check, select the posted check from the list. If the service hasn't posted status yet, type the genre/name value directly.
  4. Set Policy requirement to Required or Optional.
  5. Optionally configure Authorized identity, Reset conditions, Policy applicability, and Path filter.
    • Use Apply by default if the policy should apply as soon as the pull request is created.
    • Use Conditional if the policy should apply only after the first status is posted.
  6. Create or update a pull request that targets the branch, and confirm that the policy appears in the PR's Policies section.

For built-in Azure DevOps Services checks and their genre/name identifiers, see Available pull request status checks. For a full walkthrough of external service setup, see Configure a branch policy for an external service.

If a new integration doesn't appear in the dropdown yet, post status once from the service and then add the policy, or type the genre/name value directly.

Automatically include reviewers

You can automatically add reviewers to pull requests that change files in specific directories and files, or to all pull requests in a repo.

  1. Select the + button next to Automatically included reviewers.

    Screenshot that shows Add required reviewers.

  2. Fill out the Add new reviewer policy screen.

    Screenshot that shows the Add new reviewer policy screen.

    • Add people and groups to Reviewers.

    • Select Optional if you want to add reviewers automatically, but not require their approval to complete the pull request.

      Or, select Required if pull requests can't be completed until:

      • Every individual added as a reviewer approves the changes.
      • At least one person in every group added as a reviewer approves the changes.
      • If only one group is required, the minimum number of members you specify approve the changes.

    • Specify the files and folders that require the automatically included reviewers. Leave this field blank to require the reviewers for all pull requests in the branch.

    • Select Allow requestors to approve their own changes if pull request owners can vote to approve their own pull requests to satisfy this policy.

    • You can specify an Activity feed message that appears in the pull request.

  3. Select Save.

Allow policy bypass when needed

In some cases, you might need to bypass policy requirements. Bypass permissions let you push changes to a branch directly, or complete pull requests that don't satisfy branch policies. You can grant bypass permissions to a user or group, and scope those permissions to an entire project, a repo, or a single branch.

Two permissions allow users to bypass branch policy in different ways:

  • Bypass policies when completing pull requests applies only to pull request completion. Users with this permission can complete pull requests even if the pull requests don't satisfy policies.

  • Bypass policies when pushing applies to pushes from local repositories and edits made on the web. Users with this permission can push changes directly to protected branches without meeting policy requirements.

Screenshot showing bypass policy enforcement permissions.

For more information about managing these permissions, see Git permissions.

Important

Use caution when granting the ability to bypass policies, especially at the repo and project levels. Policies are a cornerstone of secure and compliant source code management.

Use path filters with branch policies

Several branch policies support path filters. If you set a path filter, the policy applies only to files that match the filter. Leave this field blank to apply the policy to all files in the branch.

You can specify absolute paths (the path must start with / or a wildcard) and wildcards. Examples:

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

You can specify multiple paths by using ; as a separator. Example:

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

If you prefix paths with !, you exclude them if they're otherwise included. Example:

  • /WebApp/*;!/WebApp/Tests/* includes all files in /WebApp except files in /WebApp/Tests
  • !/WebApp/Tests/* specifies no files, since nothing is included first

The order of filters is significant. Apply filters left-to-right.

Troubleshoot branch policies

Can I push changes directly to branches that have branch policies?

You can't push changes directly to branches with required branch policies unless you have permissions to bypass branch policies. You can only make changes to these branches through pull requests. You can push changes directly to branches that have optional branch policies, if they have no required branch policies.

What is autocomplete?

Branches with branch policies configured for pull requests have the Set auto-complete button. Select this option to set a pull request to autocomplete once it fulfills all policies. Autocomplete is useful when you don't expect any problems with your changes.

When are branch policy conditions checked?

The server reevaluates branch policies when pull request owners push changes and when reviewers vote. If a policy triggers a build, the build status sets to waiting until the build completes.

Can I use XAML build definitions in branch policies?

No, you can't use XAML build definitions in branch policies.

What wildcard characters can I use for required code reviewers?

Single asterisks * match any number of characters, including both forward slashes / and backslashes \. Question marks ? match any single character.

Examples:

  • *.sql matches all files with the .sql extension.
  • /ConsoleApplication/* matches all files under the folder named ConsoleApplication.
  • /.gitattributes matches the.gitattributes* file in the root of the repo.
  • */.gitignore matches any .gitignore file in the repo.

Are the required code reviewer paths case-sensitive?

No, branch policies aren't case-sensitive.

How can I configure multiple users as required reviewers, but require only one of them to approve?

You can add the users to a group, and then add the group as a reviewer. Any member of the group can then approve to meet the policy requirement.

I have bypass policy permissions. Why do I still see policy failures in the pull request status?

The system always evaluates configured policies for pull request changes. For users who have bypass policy permissions, the reported policy status is advisory only. If the user with bypass permissions approves, the failure status doesn't block pull request completion.

Why can't I complete my own pull requests when I set "Allow requestors to approve their own changes"?

Both the Require a minimum number of reviewers policy and the Automatically included reviewers policy have options to Allow requestors to approve their own changes. In each policy, the setting applies only to that policy. The setting doesn't affect the other policy.

For example, your pull request has the following policies set:

  • Require a minimum number of reviewers requires at least one reviewer.
  • Automatically included reviewers requires you or a team you're in as a reviewer.
  • Automatically included reviewers has Allow requestors to approve their own changes enabled.
  • Require a minimum number of reviewers doesn't have Allow requestors to approve their own changes enabled.

In this case, your approval satisfies Automatically included reviewers, but not Require a minimum number of reviewers, so you can't complete the pull request.

Other policies might prevent you from approving your own changes, even if Allow requestors to approve their own changes is set. For example, Prohibit the most recent pusher from approving their own changes.

What happens when a path filter doesn't start with / or a wildcard?

A path in path filters that doesn't start with / or with a wildcard has no effect. The path filter evaluates as if that path wasn't specified. Such a path can't match the / the absolute file path starts with.

Use AI to configure and manage branch policies

If you configure the Azure DevOps MCP Server, you can use natural language to gather repository, branch, pull request, and build context before you update branch policies in Azure DevOps Services.

The Azure DevOps MCP Server requires Azure DevOps Services, agent mode in your AI assistant, and Node.js 20.0+. Current MCP documentation doesn't describe direct branch-policy read or write actions, so use the Azure DevOps web portal or Azure DevOps CLI to create and update policies.

Task Example prompt
List branches in a repository List the branches in repo <Contoso.Web> in project <Contoso>
Review pull requests before tightening policy What pull requests require my review in project <Contoso>?
Inspect a pull request and linked work items Get details for pull request <67> and its linked work items in project <Contoso>
Check build status before making build validation required Get the latest build status for pipeline <Contoso-CI> in project <Contoso>

Note

If you're using Visual Studio Code, agent mode is especially helpful for gathering the project context you need before you update branch policies.

Related content

  • Last updated on