Every production bug, broken build, and late-night hotfix usually traces back to one moment: a code change that merged without enough scrutiny.
In Azure DevOps, the pull request (PR) is that checkpoint.
It's not just a merge button. It's where:
Code gets reviewed
Branch policies are enforced
Builds and tests run automatically
Work items are validated
Security and quality checks gate the merge
Done well, pull requests prevent defects from ever reaching main. Done poorly, they become bottlenecks: slow reviews, unclear feedback, merge conflicts, and policy failures that frustrate developers.
This guide walks through exactly how Azure DevOps pull requests work, from creating a PR (Web UI, CLI, Visual Studio, VS Code) to draft workflows, auto-complete, branch policies, troubleshooting common errors, and best practices for fast, high-quality reviews.
Whether you're a developer opening your first PR or a team lead standardizing review workflows, this is the complete, practical breakdown. But first, the basics: what is a pull request in ADO.
What Is a Pull Request in Azure DevOps?
A pull request (PR) in Azure DevOps is a request to merge code changes from one branch into another in Azure Repos. It creates a structured review checkpoint where team members can inspect the diff, leave inline comments, vote to approve or reject, and verify that branch policies (required reviewers, build validation, linked work items, status checks) are satisfied before the merge is allowed. If you come from GitLab, a pull request is the same thing as a merge request: different label, same gate.
Pull requests are the primary mechanism for code review in Azure DevOps. Every PR captures a complete record of what changed, who reviewed it, what feedback was given, and when it was merged, creating an auditable history of every code change that enters your codebase.
A PR in Azure DevOps consists of:
A source branch (where your changes live)
A target branch (where you want to merge)
A title and description
Linked work items from Azure Boards
Assigned reviewers
Inline review comments
Policy evaluation results, and a merge strategy
You can create PRs through the Azure DevOps web UI, the Azure CLI, Visual Studio, VS Code, or the REST API.
Anatomy of a Pull Request in Azure DevOps
Before creating your first PR, it helps to understand what each part does and why it matters for reviewers.
PR Component | What It Is | Why It Matters for Review |
|---|---|---|
Title | One-line summary of the change | First thing reviewers see. A good title lets reviewers prioritize which PRs to review first without opening them. |
Description | Detailed explanation of what changed, why, and how it was tested | Gives reviewers the context they need. Without a description, reviewers spend the first 15 minutes figuring out what they're looking at instead of whether it's correct. |
Source branch | The branch containing your code changes | Determines what diff the reviewers see. |
Target branch | The branch you're merging into (usually | Determines which branch policies apply. PRs targeting |
Reviewers | Team members assigned to review the code | Required reviewers must approve before the PR can merge. Optional reviewers provide feedback but don't block. |
Work items | Linked tasks, bugs, or stories from Azure Boards | Provides the why behind the code. Helps reviewers assess whether the implementation matches the intent. |
Labels | Tags for categorizing PRs (e.g., bug, feature, hotfix) | Helps teams filter and prioritize the PR queue. |
Policies | Branch policy evaluation results, build status, reviewer count, linked work items, status checks | The automated enforcement layer. If any required policy fails, the PR can't merge regardless of reviewer approval. |
Auto-complete | Automatic merge once all policies pass | Eliminates the "everything is approved but someone forgot to click merge" problem. |
Merge type | How the source branch is integrated into the target (merge commit, squash, rebase, semi-linear) | Affects your git history. See the merge strategies guide for tradeoffs. |
Draft status | Whether the PR is a draft (work-in-progress) or published (ready for review) | Draft PRs don't trigger policy evaluation or reviewer notifications, useful for early feedback without noise. |
Create a Pull Request: Web UI
This is the most common method. Works from any browser, no tooling required.
Step 1: Navigate to Pull Requests
Go to your Azure DevOps project, then Repos, then Pull Requests in the left sidebar. Click "New pull request" in the top-right corner. Azure DevOps also shows a Create a pull request banner right after you push a branch.
Step 2: Select Branches
Choose your source branch (the branch with your changes) from the left dropdown. Choose your target branch (where you want to merge, usually main or develop) from the right dropdown.
Azure DevOps immediately shows you the diff, all files that differ between your source and target branches. Scan this quickly to make sure you're not accidentally including unrelated changes from other branches.
Step 3: Write the Title
Use present tense. Be specific. The title should tell a reviewer what the PR does without opening it.
Good Titles | Bad Titles |
|---|---|
Fix session timeout redirect on login page | Fixed stuff |
Add rate limiting to /api/payments endpoint | Updates |
Upgrade log4j to 2.17.1 (CVE-2021-44228) | Dependency update |
Refactor UserService to use repository pattern | Refactoring |
Step 4: Write the Description
If your repo has a PR template, it auto-populates here. Fill in every section. If there's no template, write at minimum: what changed and why, how you tested it, anything reviewers should focus on, and screenshots for UI changes.
A blank PR description is the single biggest time-waster in code review. Reviewers who don't know what they're looking at or why take dramatically longer to review, ask more clarifying questions, and are more likely to miss real issues. Our PR template examples for Azure DevOps give you copy-paste starting points.
Step 5: Link Work Items
Click "Link work items" and search for the relevant Azure Boards item. Use the AB#1234 syntax in the description to auto-link. Linking work items does two things: satisfies the "Check for linked work items" branch policy (if enabled), and gives reviewers context about the business intent behind the change.
Step 6: Assign Reviewers
Add team members who know the code area. Azure DevOps supports two types: required reviewers, who must approve before the PR can merge (set via branch policies or manual assignment), and optional reviewers, who provide feedback but don't block the merge.
If your team has auto-reviewer policies configured in branch policies, reviewers may be added automatically based on file paths or code ownership rules. See our required reviewers guide for path-based auto-assignment and group strategies, and our permissions guide for who can actually approve and merge.
Step 7: Add Tags (Optional)
Add tags to categorize the PR: bug, feature, hotfix, tech-debt, documentation. Tags help teams filter the PR queue (the CLI and REST API still call them labels); a reviewer scanning 20 open PRs can quickly find the ones relevant to their area.
Step 8: Create (or Create as Draft)
Click "Create" to publish the PR and notify reviewers. Branch policies begin evaluating immediately (build validation kicks off, required reviewer checks activate, linked work item checks run). Click "Create as draft" if the PR isn't ready for formal review yet (see Draft PRs vs. Published PRs below).
Create a Pull Request: Azure CLI
The Azure CLI method is faster for developers who live in the terminal. It's also scriptable, useful for automating PR creation in pipelines or CI workflows.
Prerequisites
Install the Azure CLI and the Azure DevOps extension:
Create a Basic PR
The --open flag opens the newly created PR in your default browser.
Create a PR With Reviewers
Create a Draft PR
Useful PR Management Commands
Create a Pull Request: Visual Studio
For teams using Visual Studio 2022 with Azure Repos, you can create PRs directly from the IDE without switching to the browser.
Step 1: Open Git Changes (View, then Git Changes) or the post-push banner that appears after you push.
Step 2: Ensure you're on the branch you want to create a PR from. Push any unpushed commits.
Step 3: In the Git Changes window, or from the Git menu under GitHub/Azure DevOps, click "Create Pull Request." This opens a PR creation form within Visual Studio.
Step 4: Fill in the title, description, reviewers, and work items, the same fields as the web UI.
Step 5: Click "Create" to publish the PR, or use Create as Draft on Visual Studio 17.12 and later.
Visual Studio opens the PR in your browser after creation, where you can see the full diff and policy status. Embedded in-IDE review, votes, and completion are still rolling out, with parts behind preview flags.
Create a Pull Request: VS Code
The official Azure Repos extension for VS Code was retired from the marketplace in November 2020, so skip any guide that tells you to install it. You still have three good options.
Fastest path: run az repos pr create --open from the integrated terminal. It creates the PR and opens it in your browser.
Community extension: install AzDO Pull Requests (ankitbko.vscode-pull-request-azdo) to create and review PRs in-editor. It's third-party, not Microsoft-maintained.
Web hand-off: push your branch, then click the Create a pull request banner Azure DevOps shows for recently pushed branches.
Tip: set az devops configure --defaults organization=... project=... once, and every later az repos command gets shorter.
Draft PRs vs. Published PRs
Azure DevOps supports two PR states at creation: draft and published. Understanding when to use each can improve your team's review workflow.
Draft PR | Published PR | |
|---|---|---|
Reviewer notifications | Required and auto-included reviewers are not added, but reviewers you add explicitly do get notified | Yes, reviewers get email/Teams notifications |
Branch policy evaluation | Build validation can be queued manually; other policies wait for publish | Yes, build validation, required reviewers, and all policies evaluate immediately |
Voting | Comments allowed. Switching a published PR back to draft clears all votes | Reviewers can vote |
Merge | Cannot be merged while in draft state | Can be merged once all policies pass |
Visibility | Visible in the PR list with a "Draft" badge | Visible in the PR list as active |
When to Use Draft PRs
Early feedback on approach. You're refactoring a service and want to validate your approach before writing all the tests. Create a draft PR, tag one senior engineer, and ask: "Does this direction make sense before I go further?" No notifications sent to the full team, no builds wasting CI minutes.
Work-in-progress sharing. You're working on a feature over several days. A draft PR lets teammates see your progress, understand what you're building, and offer suggestions, without the pressure of a formal review or the noise of policy evaluation.
Pre-review self-check. Create a draft PR just to see your own diff in the Azure DevOps UI. Reading your changes in the PR view, rather than your IDE, often surfaces issues you missed: dead code, debug logs, incomplete error handling. Publish the PR once you've self-reviewed.
When to Publish Immediately
The change is ready for review. If you've already self-reviewed, written tests, and the code is in a mergeable state, skip the draft and publish directly. Draft-then-publish adds an unnecessary step.
Hotfixes. During incidents, you want reviewer notifications to fire immediately. Don't use draft for anything time-sensitive.
Small changes. A one-file config update or a documentation fix doesn't need the draft workflow. Publish, get a quick approval, merge.
Publishing a Draft PR
When a draft PR is ready for review, click "Publish" in the PR header (web UI) or run:
This triggers reviewer notifications, starts branch policy evaluation, and enables voting. The PR transitions from draft to active.
Auto-Complete: Set It and Forget It
Auto-complete is one of the most underused features in Azure DevOps. When enabled on a PR, Azure DevOps automatically merges the PR the moment all branch policies are satisfied, no manual "Complete" click required.
How Auto-Complete Works
A developer creates a PR and enables auto-complete.
Branch policies evaluate: build validation runs, required reviewers are notified, linked work items are checked.
As each policy passes, Azure DevOps checks whether all policies are now satisfied.
The moment the last policy passes (e.g., the second required reviewer approves), Azure DevOps immediately merges the PR using the configured merge strategy.
The source branch is optionally deleted (if "Delete source branch" was selected).
Setting Up Auto-Complete
Web UI: After creating a PR, click the dropdown arrow next to the "Complete" button and select "Set auto-complete." You'll be prompted to configure the merge type (merge commit, squash, rebase, or semi-linear), whether to delete the source branch after merge, whether to complete linked work items, and an optional completion message.
CLI:
When to Use Auto-Complete
Scenario | Use Auto-Complete? | Why |
|---|---|---|
Standard feature PRs | Yes | Eliminates the "everything approved but nobody merged" lag. The merge happens within seconds of final approval. |
PRs requiring manual deployment steps | No | If you need to coordinate the merge with a deployment, don't auto-merge, you need to control timing. |
PRs to release branches with deployment pipelines | Depends | If your pipeline auto-deploys on merge to |
Hotfixes | Yes | During incidents, every minute counts. Auto-complete eliminates the manual merge step. |
Draft PRs | N/A | Auto-complete can be set but won't trigger until the PR is published and all policies pass. |
Auto-Complete With Vote Reset
If your branch policies include a vote-reset policy, now a four-option "When new changes are pushed" setting that can reset all votes or only approvals, auto-complete respects this. If a reviewer approves, the author pushes new commits, and votes are reset, auto-complete pauses until the reviewer re-approves. This ensures auto-merge never happens on code that hasn't been reviewed in its final state.
PR Author Checklist
Use this checklist before creating or publishing any PR. Paste it into your PR description or use it as a mental checklist before clicking "Create."
Before creating this PR:
Changes are on a feature branch (not committing directly to main)
Branch is up to date with the target branch (rebased or merged latest)
All changes are related to one purpose (one PR, one concern)
Commit messages are clear and descriptive
Self-review:
I read my own diff line by line
No debug logs, console.logs, or print statements left in
No TODOs without linked tickets
No commented-out code
No hardcoded values that should be config or environment variables
No secrets, tokens, or credentials in the code
Description and context:
Title is specific and uses present tense
Description explains what changed and why
Work item is linked (AB# syntax)
Screenshots included (for UI changes)
Breaking changes are documented
Testing:
Unit tests added or updated for new or changed logic
All existing tests pass locally
Manual testing completed for the affected area
Edge cases considered (null inputs, empty lists, concurrent access)
Reviewers:
Correct reviewers assigned (people who know this code area)
PR size is reasonable (under 400 lines of change; split if larger)
How to Review a Pull Request in Azure DevOps
Creating a PR is half the workflow. Here's the review side, what a reviewer does from notification to vote. Worth knowing: the summary view truncates at 0.5 MB, diffs at 5 MB, and a PR caps out at 1,000 reviewers.
Step 1: Read the Overview First
Open the PR and read the Overview tab before looking at any code. Understand what the PR does (title and description), why it exists (linked work items), how it was tested, and what the author wants you to focus on.
Skipping the overview and jumping straight to the diff is the most common review mistake. You end up spending 10 minutes reverse-engineering the intent from the code instead of 30 seconds reading the description.
Step 2: Review the Diff
Switch to the Files tab. Azure DevOps shows the diff for every changed file. You can toggle between inline view (old and new code interleaved, better for small changes) and side-by-side view (old on the left, new on the right, better for large refactors).
Review files in a logical order: start with the core logic files, then tests, then configuration. Don't review in the default alphabetical order.
Step 3: Leave Inline Comments
Click on any line in the diff to leave a comment. Write comments that are specific and actionable.
Effective Comment | Ineffective Comment |
|---|---|
"This query runs inside a loop, it'll execute N times per request. Consider batching with WHERE id IN (...)" | "This needs work" |
"Missing null check on user.Email, will throw NullReferenceException if the user was created via SSO (no email required)" | "What about null?" |
"Nice approach to the caching layer, much cleaner than the previous implementation" | (saying nothing, positive feedback matters too) |
Step 4: Vote
Use the vote dropdown next to the Approve button.
Vote | What It Means | When to Use |
|---|---|---|
Approve | Code is good to merge | No issues found, or only trivial suggestions |
Approve with suggestions | Mergeable, but here are improvements for the author to consider | Non-blocking feedback. The author can merge without addressing these. |
Wait for author | Needs changes before this is mergeable | Bugs, missing tests, unclear logic, or security issues that must be fixed |
Reject | Fundamentally wrong approach, needs to be rethought | Rarely used. Only for serious architectural or directional problems. |
Step 5: Follow Up
If you voted "Wait for author," check back when the author pushes updates. Verify the fixes address your feedback. If your branch policies reset votes on new pushes, you'll need to re-review and re-vote.
How Do You Update a Pull Request After Feedback?
Push new commits to the source branch and the PR updates automatically, no reopening needed. Votes reset according to the "When new changes are pushed" policy, and reviewers can diff iteration to iteration from the Updates tab.
Requesting GitHub Copilot as a Reviewer (Preview)
As of July 2026, Copilot code review for Azure Repos is in limited public preview. You request GitHub Copilot from the Reviewers section like any human reviewer, and it comments within minutes.
Copilot always reviews as a comment-only voter, so it never satisfies required-reviewer policies and never blocks a merge. Billing runs through GitHub AI credits on the linked Azure subscription rather than a Copilot license.
Preview limits are real. Reviews cap at 100 changed files, repos at 10 GB, and there's no automatic re-review on new pushes. Sign-up rounds closed July 3, 2026, with access rolling out in waves. CodeAnt AI is GA on both Azure DevOps cloud and Server today if you need votes and quality gates that policies can actually enforce.
Troubleshooting Common Pull Request Issues
"I Can't Create a PR, Getting 'There Are No Changes' Error"
This means your source branch and target branch are identical, there's no diff. Common causes: you forgot to push your local commits (run git push origin <your-branch> and try again), you're creating a PR from the wrong branch, or your branch was already merged (check the completed PRs list).
"PR Shows Files I Didn't Change"
Your feature branch may be behind the target branch. If main has moved forward since you branched off, the diff shows both your changes and the difference between your branch's starting point and current main. Fix it by merging the latest target branch into your branch:
Or rebase:
"PR Says 'Merge Conflict' and I Can't Complete It"
Your source branch has changes that conflict with changes on the target branch. Azure DevOps can resolve some conflicts in the web UI (click "Resolve conflicts"), but for complex conflicts you'll need to resolve locally:
The PR updates automatically after you push the resolution.
"Reviewers Aren't Being Added Automatically"
Check branch policies. See our Azure DevOps branch policies guide. Auto-reviewers are configured in Repos, then Branches, then the policy menu, then Automatically included reviewers, or under Project Settings, Repository, Policies.
If this isn't configured, reviewers must be added manually on each PR. Also check whether you have a CODEOWNERS-equivalent configuration; Azure DevOps uses the "Automatically included reviewers" policy with path filters to achieve code ownership. Our required reviewers guide covers path-based auto-assignment in more depth.
"Build Validation Failed but I Don't Know Why"
Click the failed build link in the PR's policy section. This opens the Azure Pipelines build log. Common causes: a unit test failure (the build log shows which test failed and the assertion message), a compilation error, a pipeline timeout on large repos or slow tests, or an infrastructure issue where the build agent is unavailable.
"I Approved but the PR Still Says 'Not All Policies Are Met'"
Your approval is one policy, but there may be others blocking: build validation still running, minimum reviewer count not met, no linked work item, unresolved comments, or an external status check (like CodeAnt AI) that hasn't reported yet.
Check the policy section at the bottom of the PR Overview tab; each policy shows its current state (passed, failed, or pending). Our permissions guide covers who can actually override or bypass these.
"I Set Auto-Complete but the PR Isn't Merging"
Auto-complete only triggers when all policies pass simultaneously. If one policy is still pending (a reviewer hasn't approved yet, or a build is still running), auto-complete waits. Check the policy section to see which policy is blocking. Also verify the PR isn't in draft mode; draft PRs can't auto-complete.
"Error: TF402455: Pushes to This Branch Are Not Permitted"
This means branch policies are blocking direct pushes to the target branch (usually main). This is expected behavior, it means your team has configured branch protection correctly. The fix is to create a PR instead of pushing directly. This error confirms your branch policies are working.
Best Practices for Effective Pull Requests
Keep PRs small. PRs around 400 lines or less get reviewed faster and more thoroughly, the ceiling SmartBear's peer-review research famously landed on. If your change is large, split it into logical chunks: infrastructure first, core logic second, tests third.
One PR, one purpose. Don't mix a bug fix with a refactor with a new feature. Each PR should do one thing. This makes review easier, rollback safer, and git history more useful.
Write the description before the code. If you can't explain what your PR does in three sentences, you may not have a clear enough understanding of the change. Writing the description first forces you to articulate the plan.
Self-review before requesting review. Create the PR, read your own diff in the Azure DevOps UI (it looks different than in your IDE), and catch the obvious issues yourself. This shows respect for your reviewers' time and catches a meaningful share of issues before anyone else looks at it.
Respond to feedback within 24 hours. Stale PRs with unanswered feedback slow down the entire team. Even if you can't fix everything immediately, acknowledge the feedback and provide a timeline.
For a comprehensive guide to code review workflows in Azure DevOps, including branch policies, merge strategies, team-size configurations, and AI-assisted review, see AI Code Review in Azure DevOps. For squash vs. rebase decisions, see the merge strategies guide.
Automate PR Review With CodeAnt AI
PR creation is the starting point. What happens next, the actual review, is where most teams hit bottlenecks. Reviewers are busy, feedback is inconsistent, and security issues slip through.
CodeAnt AI automates the mechanical layer of PR review in Azure DevOps. When a PR is created or updated, CodeAnt AI automatically posts inline review comments on the PR diff (logical flaws, business logic errors, critical code flaws, performance issues, best practices), runs security scanning (SAST, SCA, IaC, secrets detection) with steps of reproduction showing the full attack path for every finding, auto-generates PR descriptions and summaries from the diff and linked work items, validates that PR changes align with the scope of the linked work item, and posts a quality gate status check that branch policies can gate on.
Related reading: how reproduction steps work in AI code review.
CodeAnt AI works on both cloud Azure DevOps and self-hosted Azure DevOps Server. For setup instructions, see the cloud setup guide or self-hosted setup guide. For how the full AI review pipeline works under the hood, see AI Code Review in Azure DevOps.
You can also install the CodeAnt AI extension for Azure DevOps straight from the Visual Studio Marketplace.
If you want your pull requests to be more than a merge formality, and actually become an intelligent quality gate, this is where automation makes the difference.
