How to Create a Pull Request in Azure DevOps: Step-by-Step Guide

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 you through exactly how pull requests work in Azure DevOps, 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, let’s start from the basics understanding 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.

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.

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 → Repos → Pull Requests in the left sidebar. Click “New Pull Request” in the top-right corner.

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.

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

• 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 3–5x longer to review, ask more clarifying questions, and are more likely to miss real issues.

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: must approve before the PR can merge (set via branch policies or manual assignment)

• Optional reviewers: 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.

Step 7: Set labels (optional)

Add labels to categorize the PR: bug, feature, hotfix, tech-debt, documentation. Labels help teams filter the PR queue, 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:

# Install Azure CLI (if not already installed)
# See <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli>
# Add the Azure DevOps extension
az extension add --name azure-devops
# Login and set defaults
az login
az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT

# Install Azure CLI (if not already installed)
# See <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli>
# Add the Azure DevOps extension
az extension add --name azure-devops
# Login and set defaults
az login
az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT

Create a basic PR

az repos pr create \\
  --title "Fix session timeout redirect on login page" \\
  --description "Resolves AB#1234. Fixes redirect loop when session expires during OAuth callback." \\
  --source-branch feature/login-fix \\
  --target-branch main \\
  --work-items 1234 \\
  --open
The --open flag opens the newly created PR in your default browser

az repos pr create \\
  --title "Fix session timeout redirect on login page" \\
  --description "Resolves AB#1234. Fixes redirect loop when session expires during OAuth callback." \\
  --source-branch feature/login-fix \\
  --target-branch main \\
  --work-items 1234 \\
  --open
The --open flag opens the newly created PR in your default browser

Create a PR with reviewers

az repos pr create \\
  --title "Add rate limiting to /api/payments endpoint" \\
  --description "Adds sliding-window rate limiting (100 req/min per user). See design doc: AB#5678." \\
  --source-branch feature/rate-limiting \\
  --target-branch main \\
  --reviewers "jane@company.com" "bob@company.com" \\
  --work-items 5678

az repos pr create \\
  --title "Add rate limiting to /api/payments endpoint" \\
  --description "Adds sliding-window rate limiting (100 req/min per user). See design doc: AB#5678." \\
  --source-branch feature/rate-limiting \\
  --target-branch main \\
  --reviewers "jane@company.com" "bob@company.com" \\
  --work-items 5678

Create a draft PR

az repos pr create \\
  --title "[WIP] Refactor UserService to repository pattern" \\
  --description "Draft — not ready for review. Sharing for early feedback on approach." \\
  --source-branch feature/user-service-refactor \\
  --target-branch main \\
  --draft true

az repos pr create \\
  --title "[WIP] Refactor UserService to repository pattern" \\
  --description "Draft — not ready for review. Sharing for early feedback on approach." \\
  --source-branch feature/user-service-refactor \\
  --target-branch main \\
  --draft true

Useful PR management commands

# List your open PRs
az repos pr list --creator "me" --status active
# Get details on a specific PR
az repos pr show --id 1234
# Add a reviewer to an existing PR
az repos pr reviewer add --id 1234 --reviewers "jane@company.com"
# Set auto-complete on an existing PR
az repos pr update --id 1234 --auto-complete true
# Mark a draft PR as ready for review (publish it)
az repos pr update --id 1234 --draft false
# Complete (merge) a PR
az repos pr update --id 1234 --status completed

# List your open PRs
az repos pr list --creator "me" --status active
# Get details on a specific PR
az repos pr show --id 1234
# Add a reviewer to an existing PR
az repos pr reviewer add --id 1234 --reviewers "jane@company.com"
# Set auto-complete on an existing PR
az repos pr update --id 1234 --auto-complete true
# Mark a draft PR as ready for review (publish it)
az repos pr update --id 1234 --draft false
# Complete (merge) a PR
az repos pr update --id 1234 --status completed

Create a Pull Request: Visual Studio

For teams using Visual Studio (2019 or later) with Azure Repos, you can create PRs directly from the IDE without switching to the browser.

• Step 1: Open Team Explorer (View → Team Explorer) or the Git Changes window (View → Git Changes).

• 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 Team Explorer, 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.

Visual Studio opens the PR in your browser after creation, where you can see the full diff and policy status. The in-IDE creation is mainly a convenience for Step 1-4, the actual review workflow (inline comments, voting, policy evaluation) happens in the Azure DevOps web UI.

Create a Pull Request: VS Code

With the Azure Repos extension for VS Code, you can create and manage PRs without leaving your editor.

• Step 1: Install the “Azure Repos” extension from the VS Code marketplace.

• Step 2: Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and search for “Azure Repos: Create Pull Request.”

• Step 3: Select the source branch, target branch, and fill in the title and description.

• Step 4: The extension creates the PR and provides a link to view it in the Azure DevOps web UI.

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.

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:

az repos pr update --id 1234 --draft false

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

1. A developer creates a PR and enables auto-complete

2. Branch policies evaluate: build validation runs, required reviewers are notified, linked work items are checked

3. As each policy passes, Azure DevOps checks: “Are ALL policies satisfied now?”

4. The moment the last policy passes (e.g., the second required reviewer approves), Azure DevOps immediately merges the PR using the configured merge strategy

5. 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:

• Merge type (merge commit, squash, rebase, or semi-linear)

• Whether to delete the source branch after merge

• Whether to complete linked work items (transition them to “Done” or “Closed”)

• An optional completion message (merge commit message)

CLI:

# Enable auto-complete on an existing PR
az repos pr update --id 1234 --auto-complete true
# Enable auto-complete with merge strategy
az repos pr update --id 1234 --auto-complete true --merge-commit-message "Merge PR #1234: Fix session timeout"

# Enable auto-complete on an existing PR
az repos pr update --id 1234 --auto-complete true
# Enable auto-complete with merge strategy
az repos pr update --id 1234 --auto-complete true --merge-commit-message "Merge PR #1234: Fix session timeout"

When to Use Auto-Complete

Auto-Complete with Vote Reset

If your branch policies include “Reset code reviewer votes when there are new changes,” be aware that auto-complete respects this policy. If a reviewer approves, the author pushes new commits, and votes are reset, auto-complete pauses until the reviewer re-approves. This ensures that auto-merge never happens on code that hasn’t been reviewed in its final state.

PR Author Checklist (Copy-Paste)

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/environment variables

-[ ] No secrets, tokens, or credentials in the code

## Description & 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/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 (<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.

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 + description)

• Why it exists (linked work items)

• How it was tested (description or checklist)

• What the author wants you to focus on (reviewer notes)

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)

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

Step 4: Vote

Use the vote dropdown next to the Approve button:

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.

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. Check that your source branch selector is correct.

• Your branch was already merged. Check the completed PRs list, it might already be there.

“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:

git checkout feature/your-branch

git pull origin main

git push origin feature/your-branch

Or rebase:

git checkout feature/your-branch

git rebase origin/main

git push --force-with-lease origin feature/your-branch

“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:

git checkout feature/your-branch

git pull origin main

# Resolve conflicts in your editor

git add .

git commit -m "Resolve merge conflicts with main"

git push origin feature/your-branch

The PR will update automatically after you push the resolution.

“Reviewers aren’t being added automatically”

Check branch policies. 

Auto-reviewers are configured in Project Settings → Repos → [your repo] → Policies → Branch Policies → [branch] → Automatically included reviewers. 

If this isn’t configured, reviewers must be added manually on each PR. Also check if you have a CODEOWNERS-equivalent configuration, Azure DevOps uses the “Automatically included reviewers” policy with path filters to achieve code ownership.

“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:

• Unit test failure, the build log shows which test failed and the assertion message

• Compilation error, check the build log for error messages

• Pipeline timeout, large repos or slow tests may exceed the pipeline timeout

• Infrastructure issue, the build agent may be unavailable (check agent pool status)

“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: the CI build hasn’t passed yet (or hasn’t started)

• Minimum reviewer count: the policy requires 2 reviewers but only 1 has approved

• Linked work items: no work item is linked to the PR

• Comment resolution: there are unresolved comments on the PR

• Status checks: an external status check (like CodeAnt AI) 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).

“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 (e.g., 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 that 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 solution is to create a PR instead of pushing directly. This error confirms that your branch policies are working.

Best Practices for Effective Pull Requests

Keep PRs small

PRs under 400 lines of change get reviewed faster and more thoroughly than PRs over 1,000 lines. 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 3 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 30-50% 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 the complete code review 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, covering logical flaws, business logic errors, critical code flaws, performance issues, and 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, solving the blank-description problem at the source

• Validates that PR changes align with the scope of the linked work item (ticket scope review)

• Posts a quality gate status check that branch policies can gate on

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.

Pull Requests Are the Gate: CodeAnt AI Makes Them Intelligent

Pull requests are where quality is enforced in Azure DevOps. But most teams still rely entirely on human reviewers to catch everything.

That’s the bottleneck.

Azure DevOps enforces branch policies. It runs builds. It validates work items.

But it does not:

• Analyze business logic deeply

• Explain security risks with proof of exploit paths

• Auto-generate structured PR descriptions

• Validate that code actually matches the linked work item

• Catch subtle logic flaws before a human even looks

That’s where CodeAnt AI fits into the flow.

When a PR is created or updated in Azure DevOps, CodeAnt:

• Posts inline AI review comments directly on the diff

• Runs SAST, SCA, IaC, and secrets scanning

• Provides Steps of Reproduction for security findings

• Posts a quality gate status that branch policies can enforce

• Reduces reviewer back-and-forth before humans even open the PR

That’s a modern Azure DevOps workflow.

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.

👉 Book a 30-minute demo to see CodeAnt AI running inside Azure DevOps PRs.