Branch policies and settings

  • Article

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

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

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

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

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 selecting Check for comment resolution.

Check for comment resolution

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

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

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 either a new pull request is created, or if changes are pushed to an existing pull request targeting 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 may 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 haven'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.

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.