Azure DevOps pull request work items
An Azure Repos pull request can be linked to Azure Boards work items: a branch policy can require one, and completing the pull request can move them on, for example from Active to Resolved. Below is how the pieces fit, from Microsoft's Create pull requests, Branch policies, Complete pull requests, Automate work item completion with pull requests and Repository settings.
Linking work items
- On a new pull request: under Work items to link, search by ID or title. The title search leaves out work items in a Completed or Removed state, and shows only items created or updated in the last 30 days that you created, are assigned or are authorized as.
- On an existing one: the + in the Work items area of the Overview tab. The x next to a work item removes the link; links made from the branch or from commits stay on the work item.
- From the command line (Azure DevOps Services):
az repos pr create --work-items 63 64, and for an existing pull requestaz repos pr work-item add,listandremove. - From commits: with the repository setting Commit mention linking (on by default), a commit message with
#and a work item ID links the commit to that work item.
Requiring a linked work item
The branch policy Check for linked work items, turned on under Branch Policies, requires a linked work item before the pull request can merge. Set to Optional, it only warns when none is linked. From the command line it is az repos policy work-item-linking create with --blocking true or false. In az repos pr policy list it appears as Work item linking.
Completing work items with the pull request
- The option: Complete linked work items after merging in the Complete pull request pane moves the linked work items to their completed state (Done, Closed or Completed for their type).
- Why it is already ticked: it remembers each user's last choice. That comes from the repository setting Work item transition preferences, on by default; turned off, everyone has to tick it on each pull request.
- When nothing moves: a work item already Resolved (in a process with that state, an Agile bug for example) is not moved to Closed, one already in a Completed state stays, and workflow rules can stop a transition, such as a field that must be filled to close.
- Turning it off for a repository: Project settings > Repositories > the repository > Settings, Commit mention work item resolution off. That also stops
Fixes #123in commit messages from closing work items. - A different state: in the pull request's description, put the state before the ID, for example
Resolves #123orReview #101, and that work item moves to that state when the pull request merges. - Auto-complete keeps the choice: the completion options are set along with auto-complete and used when the policies pass.
From the REST API
GET …/_apis/git/repositories/{repositoryId}/pullRequests/{pullRequestId}/workitemslists the linked work items as{"id": "23", "url": "…/_apis/wit/workItems/23"}, with a Code (Read) token (vso.code). Their titles and states come from the Work Items API, which needs Work Items access.- Completing:
PATCH …/pullrequests/{pullRequestId}with"status": "completed"and"completionOptions": {"transitionWorkItems": true, …}. The REST reference describes it as moving them "into the next logical state (i.e. Active -> Resolved)", and it is in the reference from version 4.1 (TFS 2018) on. Left out, the work items are not moved.az repos pr update --transition-work-items truedoes the same.
Work items in IntelliJ IDEA
Azure DevOps Pull Requests, a plugin by Lesstep for JetBrains IDEs 2024.1 or later and Android Studio, lists the pull requests of Azure DevOps Services and Azure DevOps Server in an IDE tool window. From version 1.0.55 a pull request shows its linked work items by number, each opening in the browser, next to the branch policies, where Linked work items says whether the policy is met. When work items are linked, its Complete dialog has Complete linked work items after merging, for completing now and for auto-complete, and remembers your last choice as the web page does. Before 1.0.55, completing from the plugin never moved them on. The review inbox, the branch policies and the work item list are free; voting, commenting, completing and creating pull requests are Pro, with a 30-day trial.
Get it on JetBrains Marketplace
Azure DevOps is a trademark of Microsoft Corporation; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by Microsoft or JetBrains.
More: auto-complete and optional policies · comment status and the comment resolution policy · merge types · pull request tags, which share their names with work item tags · 日本語