Autocomplete work items with pull requests
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
When you link a work item to a pull request (PR), you can automatically complete those work items when you complete the PR. Or, you can specify the workflow state to transition the work item to upon merging the PR.
When you link a work item to a pull request (PR), you can automatically complete those work items when you complete the PR.
For more information, see Create, view, and manage pull requests.
Prerequisites
Permissions:
- To view, follow, and edit work items, have View work items in this node and Edit work items in this node permissions set to Allow. By default, the Contributors group has these permissions. For more information, see Set work tracking permissions.
To add tags to work items, have the project-level Create new tag definition permission set to Allow. By default, the Contributors group has this permission.
Access levels:
- Be a project member.
- To add new tags to work items or to view or follow pull requests, have at least Basic access.
- To view or follow work items, have at least Stakeholder access. For more information, see About access levels.
- All project members, including those in the Readers group, can send emails containing work items.
Note
- Provide Stakeholder access to members who want to contribute to the discussion and review progress. These are typically members who don't contribute to code, but want to view work items, backlogs, boards, and dashboards.
- By default, all Contributors and Stakeholders in public projects can add new and existing tags. In private projects, Stakeholders can only add existing tags. To control the ability to create new tags, set the Create tag definition permission at the project level. For more information, see Change project-level permissions.
- GitHub permissions: Be a Contributor to the GitHub repository.
Autocomplete work items
As shown in the following image, check the box to Complete linked work items after merging. The system defaults to your selection for future PRs.
In the following circumstances, the system doesn't automatically update the work item state to Done, Closed, or Completed categories for the work item type (WIT):
- The work item, whose WIT is managed with the Inheritance process model, is already in the Resolved state. In this instance, the system doesn't update the State. For example, if a bug derived from the Agile process is in a Resolved state, the system doesn't transition it to Closed.
- The work item is already in the Completed state. No further transition is required.
- The WIT includes workflow field rules that prevent the work item from advancing to the next state. For instance, a rule might require that another field gets defined when closing the work item.
- For on-premises deployments and Azure Boards Hosted process model, you must modify the workflow to specify actions (ACTION element) to take place when transitioning the workflow. For more information, see Change the workflow for a WIT, Specify Actions.
For more information, see Customize your work tracking experience.
Specify the workflow state of linked work items
To transition a work item to a specific workflow state, you can enter the information in the pull request description. Prefix the #ID with a valid workflow state for the mentioned work item.
Note
This feature requires Azure DevOps Server 2020.1 update or later version.
The following example shows user stories that transitioned - one to the Resolved state and the other to the Review state. Also, two tasks are marked as Done.
Disable automatic completion of associated work items
To disable the automatic completion of associated work items when users complete a pull request, follow these steps:
- Go to Project settings > Repositories > select the repository.
- In the Settings tab, move the toggle to Off for Commit mention work item resolution.
Mentions in commit comments to close work items (for example, "Fixes #123") isn't allowed.