Configure a branch policy for an external service

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

Branch policies are a powerful feature to ensure high quality code in your repo by establishing requirements for all pull requests. External services can use the PR Status API to post detailed status to your PRs. The branch policy for external services brings the ability for those 3rd party services to participate in the PR workflow and establish policy requirements. This article guides you through the process of configuring a branch policy for a service that is posting PR status. For more information about PR status, see Customize and extend pull request workflows with pull request status.

Prerequisites

Category	Requirements
Project access	Member of a project.
Permissions	- View code in private projects: At least Basic access. - Clone or contribute to code in private projects: Member of the Contributors security group or corresponding permissions in the project. - Set branch or repository permissions: Manage permissions permissions for the branch or repository. - Change default branch: Edit policies permissions for the repository. - Import a repository: Member of the Project Administrators security group or Git project-level Create repository permission set to Allow. For more information, see Set Git repository permissions.
Services	Repos enabled.
Tools	Optional. Use az repos commands: Azure DevOps CLI.

Note

In public projects, users with Stakeholder access have full access to Azure Repos, including viewing, cloning, and contributing to code.

Configure the branch policy

1. Navigate to Code>Branches and find the branch that you want to configure the policy on (typically main or develop). From the context menu, select the Branch policies option.

   

2. Scroll down to find Status checks. Select the + button.

   

3. Select the service you want to create a policy for from the list. If the status has been posted previously you can pick it from the list; if it is a new policy you can type in the name of the policy.

   

   • Policy requirement determines whether or not this policy is optional or required to complete pull requests into the branch.
   • Authorized identity is used to enforce that status from only the specified identity will be counted towards the policy fulfillment.
   • Reset conditions is used to determine when a posted status is no longer valid. If the status posted is specific to the latest code (i.e. a build), check Reset status whenever there are new changes to reset the status when the source branch changes.
   • Optionally set a Path filter. Learn more about path filters in branch policies.
   • Policy applicability determines whether this policy applies as soon as a pull request is created, or whether the policy applies only after the first status is posted to the pull request.
   • Default display name allows you to specify an optional display name for your policy.

Create a new pull request

1. Create a new pull request into the branch where the policy is defined. For more information, see Create a pull request.

2. After creating the PR, the new policy will appear in the Policies section of the PR details view. Initially, the policy will appear as not set until the external service has posted status.

   

   When the service has posted status, the policy will update accordingly. Completion will be blocked until the policy approves the PR.

   

   When the policy criteria are met, and the service posts a succeeded status, the PR will be approved and completion will be unblocked.

   

Summary

In this article, you learned how to configure a branch policy for an external service.