Branch policies and settings

TFS 2018

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

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.

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.

Check for comment resolution

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

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.

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

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.

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

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.

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 third-party services to participate in the PR workflow and establish policy requirements.

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

Select reviewers for specific directories and files in your repo.

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

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.

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.

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.

Q & A

• Can I push changes directly to branches that have branch policies?
• What is autocomplete?
• When are branch policy conditions checked?
• Can I use XAML build definitions in branch policies?
• What wildcard characters can I use for required code reviewers?
• Are the required code reviewer paths case-sensitive?
• How can I configure multiple users as required reviewers, but require only one of them to approve?
• I have bypass policy permissions. Why do I still see policy failures in the pull request status?
• Why can't I complete my own pull requests when "Allow requestors to approve their own changes" is set?
• What happens when path in path filters start neither with / nor with wildcard?

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.

What happens when path in path filters start neither with / nor with wildcard?

The path in path filters that start neither with / nor with a wildcard will have no effect, and the path filter will evaluate as if that path wasn't specified. That's because such a path can't match the / the absolute file path starts with.

Related articles

• About branches and branch policies
• Configure Git repository policies using a configuration file
• Default Git permissions (Security)
• Set permissions (Security)
• Cross-service integration overview