Configure repositories and branches to integrate with work tracking

Azure Repos | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018-TFS 2017

To support traceability of your Git code with work tracking, you can exercise one or more features and configure several options.

The following table summarizes the integration points between Azure Boards and Azure Repos, Git. Through various link types, you can track code changes—commits and pull requests for Git—that support development of user stories and features. The link types used to construct these links include Branch , Commit, Pull Request, and Tag.

Conceptual image of link types that link work items to Azure Repos Git objects.



Manually link work items to Git branches, commits, pull requests, and tags

You can link from a work item or from a Git object. For details, see Link to work items from other objects, View list of linked objects.

Drive Git development from work item(s)

You can initiate a Git branch or link to Git commits or pull requests and drive your Git development cycle for a work item from within the work item form.
Screenshot of Development control for Git repositories.
For details, see Drive Git development from a work item.

Automatically link and transition work items with Git commits

Enable or disable the following options for a single Git repository. To learn how, see Configure Git repositories to support work tracking.

  • Automatically create links for work items mentioned in a commit comment
  • Allow mentions in commit comments to close work items
  • Remember user preferences for completing work items with pull requests.

Check for linked work items in a Git branch

Encourage traceability by checking for linked work items on pull requests. For details, see Configure branch policies to support work tracking.

Auto complete work items with pull requests

When you link a work item to a pull request (PR), you have the option to automatically complete those work items when you successfully complete the PR. The system defaults to your selection for future PRs. For details, see Auto complete of work items with pull requests.

Query for external links

You can query for work items that contain links to branches, commits, pull requests or tags. To learn more, see Query by link or attachment count.

Configure Git repositories to support work tracking

You can enable several options to automate linking of work items from commits or pull requests.

To configure the repository, open Project Settings>Repositories, choose a repository, and then view the Settings tab.

Screenshot of Project Settings>Repositories>Settings showing work tracking options.

Enable the following options:

  • Commit mention linking When enabled, commit messages containing # followed by a valid work item ID will automatically link the commit to the mentioned work item. Disable this option when pushing a repository previously contained by a different account or service. If you import a repository, we automatically turn this option off.
  • Commit mention work item resolution Enable this option to support closing work items mentioned in commits with the Fixes prefix, for example Fixes #*WorkItemID*.
  • Work item transition preferences When enabled, the default option, the system remembers each user's last choice to complete linked work items during pull request completion. Depending on your team's preference, you may choose to disable this option to discourage users from completing work items with their pull requests. When disabled, users must opt-in to completing work items for each pull request.

Configure branch policies to support work tracking

To ensure that changes to a branch have links to work items, you configure the branch policy for a Git repository.

To configure the branch, open Project Settings>Repositories, choose a Git repository, and then view the Policies tab. Scroll down and choose a branch under the Branch policies section. Linking work items provides additional context for your changes and ensures that updates go through your work item tracking process.

Turn on the Check for linked work items option.

  • Choose Required to mandate all pull requests have at least one linked work item in order to be completed.
  • Choose Optional to allow pull requests to be completed without linked work items, but issue a warning that there are no linked work items.

Screenshot of Project Settings>Repositories>Branch Policies showing check for linked work items option.

Require linked work items in your pull requests