Enforce Build Success and Minimum Reviews with Azure DevOps Branch Policies

Useful answer

To prevent code from being merged into a protected branch unless it passes a build and receives at least two approvals, create a branch policy that combines a Build validation policy and a Required reviewers policy. The server evaluates both conditions each time a pull request (PR) is created or updated, and the merge button remains disabled until both are satisfied.

How the mechanism works

Branch policies are stored in the repository under the .azuredevops folder and are versioned with Git. When a user opens a PR targeting a branch with policies enabled, Azure DevOps:

1. Checks each attached policy.
2. For a Build validation policy, it queues the selected pipeline and waits for a successful run.
3. For a Required reviewers policy, it counts approvals from distinct users, blocking the author from approving their own change.
4. Only when all policies report success does the service enable the Merge button.

If a policy fails, the PR page shows a red banner with the specific reason (e.g., "Build failed" or "Insufficient approvals").

Worked configuration

1. Define a build pipeline

Add a YAML file (e.g., azure-pipelines.yml) to the repository root. This example builds a .NET project and runs unit tests:

trigger:
  - main

pool:
  vmImage: 'windows-latest'

steps:
  - task: UseDotNet@2
    inputs:
      packageType: 'sdk'
      version: '6.x'
      includePreview: false

  - script: dotnet build --configuration Release
    displayName: 'Build solution'

  - script: dotnet test --configuration Release --logger trx
    displayName: 'Run tests'

Save and commit the file; Azure Pipelines will automatically detect it and create a build pipeline named after the repository (you can rename it later).

2. Attach the Build validation policy

1. Navigate to Repos → Branches.
2. Locate the target branch (e.g., main) and click the ellipsis → Branch policies.
3. Under Build validation, click + Add.
4. Select the pipeline you just created (or an existing one).
5. Set Trigger to Automatic so the build runs on every PR update.
6. Optionally enable Display build status on the pull request.
7. Save.

3. Add a Required reviewers policy

1. Still in the branch policies view, under Required reviewers, click + Add.
2. Enter the GitHub usernames or Azure AD groups that should be able to approve (e.g., [contact removed], [contact removed]).
3. Set Minimum number of reviewers to 2.
4. Check Require reviewers to vote and Allow requestor to approve their own changes (leave unchecked to enforce the rule).
5. Save.

4. Verify the combined policy

Create a new PR from a feature branch into main. The PR page will show:

• A yellow banner indicating the build is queued.
• A section listing the required reviewers with zero approvals.

Once the build succeeds, the banner turns green. After two distinct approvers submit their approvals, the merge button becomes active.

Limits and common mistakes

Limitations

• Branch policies are evaluated only at PR creation and on each update; if you change a policy after a PR is opened, the PR must be refreshed (e.g., by adding a dummy comment) to pick up the new settings.
• Policies cannot block direct pushes to the branch unless the Force push permission is denied. Users with that permission can bypass policy checks entirely.
• The build validation policy requires a valid build definition. If the pipeline is deleted or renamed, the policy silently ignores the missing build, allowing merges without validation.

Common pitfalls

1. Mis‑linked build definition: After creating a policy, verify the pipeline name appears correctly. If you see a warning like "Build definition not found", the policy will not enforce a build.
2. Insufficient permissions: Ensure the project collection administrators (or the group managing the branch) have Edit policies permission. Contributors without this cannot modify policies, leading to drift between intended and actual settings.
3. Force push oversight: A user with Force push on the repository can push directly to main, ignoring all policies. Audit the Security tab for the repository and remove Force push from groups that should not bypass policies.
4. Stale policy updates: After changing the required reviewer count, existing PRs may still show the old requirement until refreshed. Encourage teams to add a comment or push a trivial change to trigger re‑evaluation.
5. Over‑lapping policies: Adding multiple build validation policies can cause confusing status messages. Stick to one build policy per branch; combine it with other policy types (reviewers, work item linking, etc.) as needed.

Practical verification steps

1. Create a PR targeting the protected branch.
2. Confirm the build runs and shows a green check when successful.
3. Attempt to merge with only one approval; the button should stay disabled.
4. Add a second approval from a different user; the button should enable.
5. To test a failure case, temporarily introduce a failing step in the YAML (e.g., exit 1) and verify the PR blocks merge until the build passes again.

These steps let you observe the policy behavior without claiming any specific test run.