Home / CI/CD / Fix Azure DevOps Branch Policy Check Failed

CI/CD

Fix Azure DevOps Branch Policy Check Failed

Resolve Azure DevOps branch policy check failures by configuring approvers, adjusting check settings, and managing required reviewers.

Published: Apr 2, 20266 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

Introduction

Azure DevOps branch policies enforce code quality through required checks, reviewers, and approvals. When checks fail or can't be completed, pull requests remain blocked, preventing code merges.

Symptoms

Pull request blocked:

bash

"Pull request cannot be completed"
"The following policies are not satisfied:"
- "Required reviewers must approve"
- "Build validation must pass"
- "Work item must be linked"

Check failed:

yaml

# Pipeline check shows failure
##[error] Check 'RequiredReviewerCheck' failed.
# No eligible reviewers found

Approval timeout:

bash

"The check has timed out waiting for approval"
"Approval required from: [unavailable reviewers]"

Common Causes

1.Required approver unavailable - On vacation or left organization
2.Insufficient approvers - Not enough reviewers in group
3.Branch policy too strict - Requiring approval from same contributor
4.Build validation failing - Required build check not passing
5.Work item not linked - PR missing required work item
6.Merge conflicts - Unresolved conflicts blocking merge
7.Check configuration error - Misconfigured check settings

Step-by-Step Fix

1.Check logs for specific error messages
2.Verify configuration settings
3.Test network connectivity
4.Review recent changes
5.Apply corrective action
6.Verify the fix

Step 1: Check Branch Policy Settings

```bash # View branch policies az repos policy list --repository my-repo --branch main

# Check specific policy az repos policy show --policy-id 123

# Or via Azure DevOps UI: # Repos > Branches > [Branch] > Branch Policies ```

Step 2: Add Required Reviewers

```bash # Add required reviewer to policy az repos policy approver-count create \ --repository my-repo \ --branch main \ --enabled true \ --allow-downvotes false \ --creator-vote-counts false \ --reset-on-source-push false \ --minimum-approver-count 2

# Add specific required reviewer az repos policy required-reviewer create \ --repository my-repo \ --branch main \ --enabled true \ --reviewer-type Required \ --reviewer-ids user@example.com ```

Step 3: Update Check Configuration

```yaml # In azure-pipelines.yml, configure checks resources: repositories: - repository: self type: git name: my-project/my-repo

# Branch policy with checks trigger: branches: include: - main - feature/*

pr: branches: include: - main policies: requiredReviewers: - user@example.com minimumApprovers: 2 ```

Step 4: Fix Unavailable Reviewer

```bash # If required reviewer is unavailable, update policy # Option 1: Add backup reviewer az repos policy required-reviewer update \ --policy-id 123 \ --reviewer-ids backup@example.com

# Option 2: Use group instead of individual az repos policy required-reviewer update \ --policy-id 123 \ --reviewer-ids "team-group"

# Option 3: Temporarily disable policy az repos policy update --policy-id 123 --enabled false ```

Step 5: Configure Bypass Policies

```bash # Allow specific users to bypass policies # Project Settings > Repositories > [Repo] > Security # Set "Bypass branch policies" to Allow for specific users/groups

# Via CLI: az devops security permission update \ --namespace-id "2e9eb7ed-32c3-427a-a321-82a4e8b5b2c2" \ --subject user@example.com \ --token "repoV2/PROJECT_ID/REPO_ID" \ --allow-bit 8192 # Bypass policies permission ```

Step 6: Fix Build Validation Check

```bash # Check build policy configuration az repos policy build create \ --repository my-repo \ --branch main \ --build-definition-id 456 \ --enabled true \ --queue-on-source-update-only false \ --manual-queue-only false \ --display-name "Build Validation" \ --valid-duration 720

# If build is failing, check build logs az pipelines runs show --run-id 789 ```

Step 7: Link Work Items

```bash # PR must have linked work item # Azure DevOps UI: PR > Linked work items > Add

# Via CLI (link work item to PR) az boards work-item relation add \ --id 12345 \ --relation-type "ArtifactLink" \ --target "vstfs:///Git/PullRequestId/PROJECT/REPO/PR_ID" ```

Step 8: Resolve Merge Conflicts

```bash # Check for merge conflicts git fetch origin git checkout feature-branch git merge origin/main

# Resolve conflicts # After resolving: git add . git commit -m "Resolve merge conflicts" git push ```

Step 9: Use Auto-Complete with Policies

```yaml # Set PR to auto-complete when policies are satisfied # Azure DevOps UI: PR > Set auto-complete

# Via API: curl -X PATCH \ "https://dev.azure.com/ORG/PROJECT/_apis/git/repositories/REPO/pullrequests/PR_ID?api-version=6.0" \ -H "Authorization: Basic $(echo :$PAT | base64)" \ -H "Content-Type: application/json" \ -d '{ "autoCompleteSetBy": {"id": "USER_ID"}, "completionOptions": { "mergeCommitMessage": "Auto-merged PR", "deleteSourceBranch": true, "mergeStrategy": "squash" } }' ```

Step 10: Monitor Policy Compliance

```bash # Create dashboard for policy compliance # Azure DevOps > Dashboards > New dashboard

# Add widget for: # - Pull request status # - Policy compliance # - Build status

# Set up alert for stuck PRs # Project Settings > Notifications > New subscription # Filter: Pull request created > Wait time > 24 hours ```

Branch Policy Configuration Reference

Policy	Setting	Recommendation
Minimum reviewers	Count	2 for production
Require specific reviewers	Users/groups	Use groups, not individuals
Creator vote counts	Boolean	false (must have external approval)
Reset votes on push	Boolean	true for clean history
Build validation	Pipeline	Required for main branches
Work item linking	Required	true for traceability

Verification

```bash # After updating policy, check PR status az repos pr show --id 123 --query '{Status:status,Reviewers:reviewers}'

# Should show: # - Status: active (can be completed) # - Reviewers: with votes

# Attempt to complete PR az repos pr update --id 123 --status completed

# If still blocked, check remaining policy failures az repos pr show --id 123 --query 'mergeStatus' ```

[Fix Azure DevOps Agent Pool Full](/articles/fix-azure-devops-agent-pool-full)
[Fix Azure DevOps Service Connection Failed](/articles/fix-azure-devops-service-connection-failed)
[Fix Azure DevOps Variable Group Not Loading](/articles/fix-azure-devops-variable-group-not-loading)

[Technical troubleshooting: Fix Cicd Artifact Upload Failed Storage Issue in C](cicd-artifact-upload-failed-storage)
[Technical troubleshooting: Fix Cicd Code Quality Gate Failed Sonarqube Issue ](cicd-code-quality-gate-failed-sonarqube)
[Technical troubleshooting: Fix Cicd Deployment Failed Health Check Issue in C](cicd-deployment-failed-health-check)
[Technical troubleshooting: Fix Cicd Github Actions Workflow Queue Timeout in ](cicd-github-actions-workflow-queue-timeout)
[Technical troubleshooting: Fix Cicd Gitlab Runner Stuck Pending Issue in CI/C](cicd-gitlab-runner-stuck-pending)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

Azure DevOps Branch Policy Check Failed Azure DevOps Branch Policy Check Failed CI/CD Azure DevOps Branch Policy Check Failed troubleshooting Azure DevOps Branch Policy Check Failed fix Resolve Azure DevOps branch policy check failures by configuring approvers, adjusting check settings, and managing required reviewers CI/CD Resolve Azure DevOps branch policy check failures by configuring approvers, adjusting check settings, and managing required reviewers

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

CI/CD Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this cicd-errors troubleshooting guide applies to my situation?

This guide is designed for cicd-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these cicd-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of cicd-errors issue?

Most cicd-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this cicd-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for cicd-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Apr 2, 2026

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation

Fix Azure DevOps Branch Policy Check Failed

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Check Branch Policy Settings

Step 2: Add Required Reviewers

Step 3: Update Check Configuration

Step 4: Fix Unavailable Reviewer

Step 5: Configure Bypass Policies

Step 6: Fix Build Validation Check

Step 7: Link Work Items

Step 8: Resolve Merge Conflicts

Step 9: Use Auto-Complete with Policies

Step 10: Monitor Policy Compliance

Branch Policy Configuration Reference

Verification

People also search for

Browse Guides from Other Categories

WordPress

SSL

DNS

CI/CD Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading

Fix Azure DevOps Branch Policy Check Failed

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Check Branch Policy Settings

Step 2: Add Required Reviewers

Step 3: Update Check Configuration

Step 4: Fix Unavailable Reviewer

Step 5: Configure Bypass Policies

Step 6: Fix Build Validation Check

Step 7: Link Work Items

Step 8: Resolve Merge Conflicts

Step 9: Use Auto-Complete with Policies

Step 10: Monitor Policy Compliance

Branch Policy Configuration Reference

Verification

Related Issues

Related Articles

People also search for

Share this guide

More CI/CD Troubleshooting Guides

Browse Guides from Other Categories

CI/CD Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading