Autocomplete work items with pull requests

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

When you link a work item to a pull request (PR), you can automatically complete those work items when you complete the PR. Alternatively, you can specify the workflow state to transition the work item to upon merging the PR.

This automation streamlines your development workflow by ensuring that work items reflect the current state of your code changes without manual intervention.

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

Prerequisites

Autocomplete work items

To enable automatic completion of linked work items when you merge a pull request, select the checkbox Complete linked work items after merging, as shown in the following image. The system saves your selection as the default for future PRs.

When automatic completion doesn't occur

The system doesn't automatically update the work item state to Done, Closed, or Completed categories for the work item type (WIT) in the following circumstances:

• Work item already in Resolved state: The work item, whose WIT uses 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.
• Work item already completed: The work item is already in the Completed state category. No further transition is required.
• Workflow rules prevent transition: The WIT includes workflow field rules that prevent the work item from advancing to the next state. For instance, a rule might require that you define another field when closing the work item.
• On-premises workflow configuration: 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 about customizing workflows, see Customize your work tracking experience.

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. Navigate to Project settings > Repositories > select your repository.
2. In the Settings tab, turn Off the toggle for Commit mention work item resolution.

When you disable this setting, the system doesn't allow mentions in commit comments to close work items (for example, "Fixes #123"). This setting affects both pull request completion and direct commit mentions.

Best practices

Consider these best practices when using automatic work item completion:

• Review work item states: Before enabling automatic completion, ensure your work item states align with your team's workflow expectations.
• Use specific state transitions: When you need precise control, use the state transition syntax in pull request descriptions rather than relying on default completion behavior.
• Test workflow rules: Verify that any custom workflow rules don't prevent automatic state transitions.
• Communicate with your team: Ensure all team members understand how automatic completion affects work item tracking.

Troubleshooting

If work items don't automatically complete as expected:

1. Check permissions: Verify you have the necessary permissions to edit work items.
2. Review workflow rules: Ensure no workflow field rules prevent the state transition.
3. Validate work item links: Confirm the work items are properly linked to the pull request.
4. Check current state: Verify the work item isn't already in a completed state.
5. Review repository settings: Ensure automatic completion is enabled in repository settings.

Related content

• 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
• Link work items to other objects