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

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

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.

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.

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.

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.

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

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.

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.

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.

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.