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.

For more information, see Create, view, and manage pull requests.

Prerequisites

• Project access: Be a project member.

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

  • 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.
  • Stakeholders can't add new tags, even if the permission is explicitly set, due to their access level. For more information, see Stakeholder access quick reference.

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

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:

1. Go to Project settings > Repositories > select the repository.
2. 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.

Related articles

• Create, view, and manage pull requests
• Customize the workflow (Inheritance process)
• Customize your work tracking experience
• How workflow states and state categories are used in Backlogs and Boards