Training
Module
Collaborate with pull requests in Azure Repos - Training
Collaborate with pull requests in Azure Repos
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Visual Studio 2019 | Visual Studio 2022
Create pull requests (PRs) to change, review, and merge code in a Git repository. You can create PRs from branches in the upstream repository or from branches in your fork of the repository. Your team can review the PRs and give feedback on changes. Reviewers can step through the proposed changes, leave comments, and vote to approve or reject the PRs. Depending on branch policies and other requirements, your PR might need to meet various criteria before you can complete the PR and merge the changes into the target branch.
For PR guidelines and management considerations, see About pull requests.
azure-devops
extension. For more information, see Get started with Azure DevOps CLI.
az repos pr
.For more information about permissions and access, see Default Git repository and branch permissions and About access levels.
You can create a new PR from the Azure DevOps project website, from Visual Studio, or from the Azure DevOps CLI.
To create a new PR in your project, use az repos pr create. To open the PR in your browser after creation, use the --open
parameter.
az repos pr create [--auto-complete {false, true}]
[--bypass-policy {false, true}]
[--bypass-policy-reason]
[--delete-source-branch {false, true}]
[--description]
[--detect {false, true}]
[--draft {false, true}]
[--merge-commit-message]
[--open]
[--org]
[--project]
[--repository]
[--reviewers]
[--source-branch]
[--squash {false, true}]
[--subscription]
[--target-branch]
[--title]
[--transition-work-items {false, true}]
[--work-items]
Parameter | Description |
---|---|
--auto-complete |
Set the pull request to complete automatically and merge into the target branch when all policies pass. Accepted values: false , true . |
--bypass-policy |
Bypass any required policies and complete the pull request once it's mergeable. Accepted values: false , true . |
--bypass-policy-reason |
Reason for bypassing required policies. |
--delete-source-branch |
Delete the source branch after the pull request is completed and merged into the target branch. Accepted values: false , true . |
--description -d |
Description for the new pull request, which can include Markdown. Each value is a new line. For example: --description "First Line" "Second Line" . |
--detect |
Automatically detect organization. Accepted values: false , true . |
--draft |
Create the pull request in draft mode as work in progress. Accepted values: false , true . |
--merge-commit-message |
Message that shows when you merge commits. |
--open |
Open the pull request in your web browser. |
--org --organization |
Azure DevOps organization URL. You can configure the default organization using az devops configure -d organization=ORG_URL . Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/ . |
--project -p |
Name or ID of the project. You can configure the default project using az devops configure -d project=NAME_OR_ID . Required if not configured as default or picked up via git config. |
--repository -r |
Name or ID of the repository to create the pull request in. Required parameter. |
--reviewers |
Additional users or groups to include as reviewers on the new pull request. Space separated. |
--source-branch -s |
Name of the source branch. Example: "dev" . |
--squash |
Squash the commits in the source branch when merging into the target branch. Accepted values: false , true . |
--subscription |
Name or ID of the Azure subscription. You can configure the default subscription by using az account set -s NAME_OR_ID . |
--target-branch -t |
Name of the target branch. If not specified, defaults to the default branch of the target repository. |
--title |
Title for the new pull request. |
--transition-work-items |
Transition any work items linked to the PR into the next logical state when the PR changes status. For example change, Active work items to Resolved. Accepted values: false , true . |
--work-items |
IDs of work items to link to the new pull request. Space separated. |
The following command creates a PR from the new
branch to the default main
branch of the Fabrikam repository, opens the PR in the browser, and shows the command output in a table. The example uses the default configuration: az devops configure --defaults organization=https://dev.azure.com/fabrikamprime project="Fabrikam Fiber"
.
az repos pr create --repository Fabrikam --source-branch new --open --output table
ID Created Creator Title Status IsDraft Repository
---- ---------- ------------------- ---------------------------- -------- --------- ------------
30 2021-10-31 jamalh@fabrikam.com Updated note-new-git-tool.md Active False Fabrikam
You can add many other PR details at or after PR creation. To add details, reviewers, work items, and completion options to the PR, see Add details or edit PRs.
Azure DevOps CLI commands aren't supported for Azure DevOps Server.
You can copy commits from one branch to another by using cherry-pick. Unlike a merge or rebase, cherry-pick only brings the changes from the commits you select, instead of all the changes in a branch.
To cherry-pick changes from a completed PR, select Cherry-pick on the PR's Overview page. To copy changes from an active PR, select Cherry-pick from the PR's More options menu. This action creates a new branch with the copied changes. You can then create a new PR from the new branch. For detailed instructions, see Copy changes with cherry-pick.
Before the first time you save a PR, you can switch the source and target branches of the PR by selecting the Switch source and target branches icon next to the branch names. Once the PR is active, this icon goes away, but you can still change the target branch of the PR.
A pull request template is a file containing Markdown text that populates the PR description when you create a PR. Good PR descriptions tell PR reviewers what to expect, and can help track tasks like adding unit tests and updating documentation. Your team can create a default PR template that adds text to all new PR descriptions in the repo. Also, you can select from branch-specific templates or other templates your team defines. For more information about creating and using PR templates, see Improve pull request descriptions using templates.
If your repo has a default template, all PRs in the repo have the default template's description text at creation. To add other templates, select Add a template and then choose a template from the dropdown list. You can edit the template text in your description, remove it, or add other text.
If your PR isn't ready for review, you can create a draft PR to indicate work in progress. When the PR is ready for review, you can publish it, and begin or resume the full review process.
Draft PRs have the following differences from published PRs:
Build validation policies don't run automatically. You can queue build validations manually by selecting the more options menu in the PR.
Voting is disabled while in draft mode.
Required reviewers aren't automatically added. Notifications are sent only to reviewers that you explicitly add to the draft PR.
Draft PRs display in the PR list with a Draft badge.
Note
Creating draft PRs requires Azure DevOps Server 2019.1 update or later version.
To create a PR as a draft, set the --draft
parameter to true
when you create the PR. (Requires Azure DevOps Server 2020 or later version.)
For example:
az repos pr create --repository Fabrikam --source-branch new --draft true
To set an existing PR to draft, use az repos pr update --id <PR Id> --draft true
.
To remove draft status from a PR, set --draft
to false
.
Azure DevOps CLI commands aren't supported for Azure DevOps Server.
You can add details during PR creation with az repos pr create, or update details in existing PRs with az repos pr update.
When you create a PR with az repos pr create
, add a --title
and a detailed --description
of your changes so others can see what problems the changes solve. The --description
parameter accepts Markdown entry, and each value in the argument is a new line of the PR description.
For example:
az repos pr create --repository Fabrikam --source-branch new --title "Update the readme" --description "This PR updates the readme." "These are *new* changes."
Keep these fields up to date so reviewers can understand the changes in the PR. To update details of a PR, use az repos pr update
with the required PR --id
parameter.
For example, to update the title and description for PR #21, use:
az repos pr update --id 21 --description "These updates are *no longer new*." --title "Old updates"
Azure DevOps CLI commands aren't supported for Azure DevOps Server.
You can add optional reviewers to a PR at creation withaz repos pr create --reviewer "<Reviewer Name>" "<Another Reviewer>"
.
For example:
az repos pr create --repository Fabrikam --source-branch new --reviewer "[Fabrikam]\Fabrikam Team" "[Fabrikam Fiber]\Web"
To add required reviewers, or change reviewers between optional and required, open and update the PR in the browser.
To manage reviewers for an existing PR, use az repos pr reviewer.
az repos pr reviewer add --id <PR Id> --reviewer "<Reviewer Name>" "<Another Reviewer>"
.az repos pr reviewer list --id <PR Id>
.az repos pr reviewer remove --id <PR Id> --reviewer "<Reviewer Name>"
.az repos pr reviewer add --id
--reviewers
[--detect {false, true}]
[--org]
[--subscription]
Parameter | Description |
---|---|
--id |
ID of the pull request. Required. |
--reviewers |
Users or groups to include as reviewers on a pull request. Space separated. Required. |
--detect |
Automatically detect organization. Accepted values: false , true . |
--org --organization |
Azure DevOps organization URL. You can configure the default organization by using az devops configure -d organization=<ORG_URL> . Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/ . |
--subscription |
Name or ID of Azure subscription. You can configure the default subscription by using az account set -s <NAME_OR_ID> . |
Azure DevOps CLI commands aren't supported for Azure DevOps Server.
You can link Azure Boards work items to PRs at PR creation with az repos pr create --work-items <Id1> <Id2>
, where <Id> is the work item's ID.
For example, the following command links work items #63 and #64 to a new PR in the new
branch:
az repos pr create --repository Fabrikam --source-branch new --work-items 63 64
To manage work items for an existing PR, use az repos pr work-item.
az repos pr work-item add --id <PR Id> --work-items <Id1> <Id2>
.az repos pr work-item list --id <PR Id>
.az repos pr work-item remove --id <PR Id> --work-items <Id1>
.
Unlinking only removes the link between the work item and the PR. Links created in the branch or from commits stay in the work item.az repos pr work-item add --id
--work-items
[--detect {false, true}]
[--org]
[--subscription]
Parameter | Description |
---|---|
--id |
ID of the pull request. Required. |
--work-items |
IDs of the work items to link. Space separated. Required. |
--detect |
Automatically detect organization. Accepted values: false , true . |
--org --organization |
Azure DevOps organization URL. You can configure the default organization by using az devops configure -d organization=<ORG_URL> . Required if not configured as default or picked up via git config. Example: https://dev.azure.com/MyOrganizationName/ . |
--subscription |
Name or ID of Azure subscription. You can configure the default subscription by using az account set -s <NAME_OR_ID> . |
Azure DevOps CLI commands aren't supported for Azure DevOps Server.
Use tags to show important details and help organize PRs. Tags can communicate extra information to reviewers, such as that the PR is still a work in progress, or is a hotfix for an upcoming release.
To add a tag when creating a PR, type a tag name in the Tags section. After you create the PR, you can manage tags in the Tags section.
You can attach files, including images, to your PR during or after creation. Select the paper clip icon below the Description field, or drag and drop files directly into the Description field of the PR.
For most teams, nearly all PRs target a default branch, such as main
or develop
. If you sometimes need to target a different branch, it's easy to forget to change the target branch when you create the PR. If that happens, you can change the target branch of an active PR:
You can share a pull request by email to notify reviewers and communicate with team members. To share a PR:
Select More options on the PR Overview page, and then select Share pull request.
On the Share pull request screen, add recipients by typing their names in the To: field and selecting from the user names that appear. You can also remove recipients.
Add an optional message in the Note (Optional) field, and then select Send. Recipients receive an email requesting their attention and linking to the PR.
Note
If you use the built-in email feature, you can only send the email to project members' individual addresses. Adding a team group or security group to the To: line isn't supported. If you add an email account that the system doesn't recognize, you receive a message that one or more recipients of your email don't have permissions to read the mailed pull request.
For the email feature to work, your administrator for Azure DevOps Server must configure an SMTP server.
Training
Module
Collaborate with pull requests in Azure Repos - Training
Collaborate with pull requests in Azure Repos
Documentation
Complete, abandon, or revert pull requests - Azure Repos
Respond to comments and complete pull requests in Azure Repos. Learn about completion options, auto-completion, and abandoning or reverting pull requests.
Review and comment on pull requests - Azure Repos
Learn how to review pull requests using Git in Azure Repos, including making comments, adding suggestions, and voting on changes.
About pull requests and permissions - Azure Repos
Learn about pull request guidelines, management, and considerations when working in an Azure Repos Git repository.