Branch policies and settings

TFS 2017 | TFS 2015

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 that has required policies configured can't be deleted, and requires pull requests (PRs) for all changes.

Prerequisites

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

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:

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.

Check for comment resolution

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

Build validation

Automatically include code reviewers

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.

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

  • When completing a pull request, opt-in to override policies and complete a pull request even if the current set of branch policies is not satisfied.
  • Push directly to a branch even if that branch has branch policies set. Note that 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.

Q & A

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

You can't push changes directly to branches that have 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.