Edit

Share via

Branch policies and settings

  • Article

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Branch policies help teams protect their important branches of development. Policies enforce your team's code quality and change management standards. This article describes how to set and manage branch policies. For an overview of all repository and branch policies and settings, see Git repository settings and policies.

A branch with required policies configured can't be deleted, and requires pull requests (PRs) for all changes.

Prerequisites

  • To set branch policies, you must be a member of the Project Administrators security group or have repository-level Edit policies permissions. For more information, see Set Git repository permissions.

Configure branch policies

To manage branch policies, select Repos > Branches to open the Branches page in the web portal.

Screenshot that shows the Branches menu item.

You can also get to branch policy settings with Project Settings > Repository > Policies > Branch Policies > <Branch Name>.

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

To set branch policies, locate the branch you want to manage. You can browse the list or search for your branch in the Search branch name box at upper right.

Select the More options icon next to the branch, and then select Branch policies from the context menu.

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

Locate your branch in the page. You can browse the list or you can search for your branch using the Search all branches box in the upper right.

Screenshot that shows the Branches page.

Select the ... button. Select Branch policies from the context menu.

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

Configure policies on the branch's settings page. See the following sections for descriptions and instructions for each policy type.

Configure your policies in the Policies page. See the following sections for descriptions of each policy type. Select Save changes to apply your new policy configuration.

Screenshot that shows the Policies tab.

Require a minimum number of reviewers

Code reviews are important for software development projects. To ensure that teams review and approve PRs, you can require approval from a minimum number of reviewers. The basic policy requires that a specified number of reviewers approve the code, with no rejections.

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 does'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 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.
  • 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.

Check the Require Code Reviews box

  • If Requestors can approve their own changes isn't selected, the creator of the pull request can still vote Approve on their pull request, but their vote doesn't count toward the Minimum number of reviewers.
  • If any reviewer rejects the changes, the pull request can't complete unless you select Allow completion even if some reviewers vote to wait or reject.
  • You can reset code reviewer votes when new changes are pushed to the source branch. Select Reset code reviewer votes when there are new changes.

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

Check for 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 linked work items in your pull requests

Check for comment resolution

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

Configure a comment resolution policy for your branch by setting Check for comment resolution to On. Then select whether to make the policy Required or Optional.

Screenshot of Check for comment resolution.

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

Configure a comment resolution policy for your branch by selecting Check for comment resolution.

Check for comment resolution

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

Limit merge types

Azure Repos has several merge strategies, and by default, all of them are allowed. You can maintain a consistent branch history by enforcing a merge strategy for PR completion.

Set Limit merge types to On to limit which merge types to allow 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 with 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.

Note

This feature is available for Azure DevOps Server 2020 and later versions.

Enforce a merge strategy

Maintain a consistent branch history by enforcing a merge strategy when a pull request completes. Select Enforce a merge strategy and pick an option to require that pull requests merge using that strategy.

Set merge requirements

  • No fast-forward merge - This option merges the commit history of the source branch when the pull request closes and creates a merge commit in the target branch.
  • Squash merge - Complete all pull requests with a squash merge, creating a single commit in the target branch with the changes from the source branch. Learn more about squash merging and how it affects your branch history.

Build validation

You can set a policy requiring 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.

A build validation policy queues a new build when a new PR is created or changes are pushed to an existing PR that targets the branch. The build policy evaluates the build results to determine whether the PR can be completed.

Important

Before specifying a build validation policy, you must have 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.

  3. 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.

Note

This feature is available for Azure DevOps Server 2020 and later versions.

Set a policy requiring changes in a pull request to build successfully with the protected branch before the pull request can be completed. 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.

If a build validation policy is enabled, a new build is queued when a new pull request is created or when changes are pushed to an existing pull request that targets the branch. The build policy then evaluates the results of the build to determine whether the pull request can be completed.

Important

Before specifying a build validation policy, you must have a build definition. If you don't have one, see Create a build definition and choose the type of build that matches your project type.

Add build policy

Choose Add build policy and configure your options in Add build policy.

Build policy settings

  1. Select the Build definition.

  2. Choose the type of Trigger. Select Automatic (whenever the source branch is updated) or Manual.

  3. Select the Policy requirement. If you choose Required, builds must complete successfully to complete pull requests. Choose Optional to provide a notification of the build failure but still allow pull requests to complete.

  4. Set a build expiration to make sure that updates to your protected branch don't break changes for open pull requests.

    • Immediately when branch name is updated: This option sets the build policy status in a pull request to failed when the protected branch is updated. Requeue a build to refresh the build status. This setting ensures that the changes in pull requests build successfully even as the protected branch changes. This option is best for teams that have important branches with a lower volume of changes. Teams working in busy development branches might find it disruptive to wait for a build to complete every time the protected branch is updated.
    • 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 entered. This option is a compromise between always requiring a build when the protected branch updates and never requiring one. This choice is excellent for reducing 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 for your branch. It can cause problems when closing pull requests that weren't updated recently.

  5. 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 definition name.

  6. Select Save.

When the owner pushes changes that build successfully, the policy status is updated. If you have an Immediately when branch name is updated or After n hours if branch name has been updated build policy chosen, the policy status updates when the protected branch is updated if the most recent build is no longer valid.

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.

For instructions on configuring this policy, see Configure a branch policy for an external service.

Require approval from external services

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

Require external services to approve

For instructions on configuring this policy, see Configure a branch policy for an external service.

Automatically include code 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.

Note

This feature is available for Azure DevOps Server 2020 and later versions.

Select reviewers for specific directories and files in your repo.

Enter the path and required reviewers

These reviewers are automatically added to pull requests that change files along those paths. You can also specify an Activity feed message.

Add automatic reviewers

If you select Required, then the pull request can't be completed until:

  • Every user added as a reviewer for the path approves the changes.
  • At least one person in every group added to the path approves the changes.
  • The number of reviewers specified for every group added to the path approves the changes.

Required reviewers are automatically added

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

You can select Requestors can approve their own changes.

When all required reviewers approve the code, you can complete the pull request.

Pull request status shows that reviewers have approved

Bypass branch policies

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. You can scope bypass 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.

In TFS 2015 through TFS 2018 Update 2, the Exempt from policy enforcement permission allows users with this permission to perform the following actions:

  • Opt-in to override policies and complete a pull request even if the current set of branch policies isn't satisfied.
  • Push directly to a branch even if that branch has branch policies set. When a user with this permission makes a push that would override branch policy, the push automatically bypasses branch policy with no opt-in step or warning.

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.

Path filters

Several branch policies offer path filters. If a path filter is set, the policy applies only to files that match the path filter. Leaving this field blank means that the policy applies to all files in the branch.

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

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

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

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

Paths prefixed with ! are excluded if they would otherwise be 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. Filters are applied left-to-right.

Q & A

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. Changes to these branches can be made only 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?

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

When are branch policy conditions checked?

Branch policies reevaluate on the server 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 back-slashes \. 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?

Configured policies are always evaluated for pull request changes. For users that 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 "Allow requestors to approve their own changes is set"?

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.

There might also be other policies, such as Prohibit the most recent pusher from approving their own changes, that prevent you from approving your own changes even if Allow requestors to approve their own changes is set.

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

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