How to link an Azure Boards work item to a branch or pull request

Azure Boards tracks what needs to be done. Azure Repos stores the code changes that do it. Connecting these two systems — linking a work item to the branch or pull request that contains the code change — is the foundation of a traceable development workflow.

This guide explains what Development links are, how to create and manage them, and why they matter for deployments as well as traceability.

What Development links are

Azure Boards work items have a Development section that tracks links to Azure Repos artefacts: branches and pull requests. This is distinct from Related Work links, which connect work items to other work items, and External Links, which point to external resources.

Development links appear on the work item details page, usually beneath the description and any attachments. When you open a work item and see "1 branch" or "1 pull request" in the Development section, those are Development links.

These links are created automatically when you:

• Create a branch from within the work item using the "Create branch" option in the Development section.
• Reference a work item ID in a commit message using the AB#1234 syntax.
• Link a pull request to a work item from the PR side.

They can also be added manually from the work item's Development section.

How to create a branch from a work item

Creating a branch directly from the work item is the simplest way to establish a Development link automatically.

1. Open the work item in Azure Boards.
2. Scroll to the Development section on the right-hand side of the work item.
3. Click Create a branch.
4. Select the repository you want to create the branch in.
5. Choose a base branch (typically main or develop).
6. Enter a branch name. Azure DevOps suggests a name based on the work item title and ID.
7. Click Create branch.

The new branch is created in Azure Repos and a Development link appears on the work item immediately. Developers can now checkout this branch and begin work.

How to link a pull request to a work item

When a developer creates a pull request in Azure Repos to merge a feature branch, they can link it to the work item it addresses. This can be done from either side.

From the pull request

1. Open the pull request in Azure Repos.
2. In the PR description or the right-hand panel, find Work items.
3. Search for and select the work item the PR addresses.
4. The link appears on both the PR and the work item's Development section.

From the work item

1. Open the work item in Azure Boards.
2. In the Development section, click the link icon or Add link.
3. Select Pull request as the link type.
4. Search for the PR by ID or title.
5. Save the link.

Using the AB# commit syntax

If a developer includes AB#1234 in a commit message (where 1234 is the work item ID), Azure DevOps automatically creates a Development link between the commit and the work item. When that commit becomes part of a pull request, the PR also gets linked to the work item.

This is the most friction-free way to keep work items and code linked, because it happens at commit time without requiring a separate UI action.

How to check linked branches and PRs on a work item

To see all branches and PRs linked to a work item:

1. Open the work item in Azure Boards.
2. Scroll to the Development section.
3. Expand the section to see all linked branches and pull requests, their current status, and the repository they belong to.

Each linked branch shows whether it has been merged and which repository it belongs to. Each linked PR shows the PR title, status (active, completed, or abandoned), and reviewer count.

Why these links matter for traceability

Development links create an audit trail that connects your planning to your code. When a work item has a linked branch and a linked PR, you can:

• See at a glance whether work on a ticket has started (linked branch exists) and whether it is ready to merge (PR is open or completed).
• Navigate directly from the work item to the diff, comments, and CI results for the branch.
• Query work items by development status — for example, find all tickets in a sprint with an open PR that hasn't been merged.
• Know exactly which commit and which branch corresponds to which piece of work when diagnosing a production issue.

This traceability also matters for compliance and audit purposes in teams that need to demonstrate change management processes.

How BranchDeploy uses linked branches and PRs

BranchDeploy reads the Development section of the work item to identify which Azure Repos branch or pull request to deploy. When you click the BranchDeploy action on a work item:

• If the work item has a linked branch, BranchDeploy uses that branch as the deployment source.
• If the work item has a linked PR, BranchDeploy resolves the PR's source branch (the feature branch being merged, not the target branch).
• If the work item has multiple linked branches or PRs (Pro feature), BranchDeploy shows a picker so the user can select the correct source.

This means the link you create between a work item and a branch or PR is not just for tracking — it directly drives the deployment. The branch that gets deployed to staging or UAT is the branch the developer was working on, resolved automatically from the ticket.

Once your work items are linked to branches or PRs, BranchDeploy can use those links to deploy the right branch from the ticket.

Troubleshooting

BranchDeploy says "no linked branch found"

This means the work item does not have a Development link to a branch or PR. Check:

• The Development section of the work item in Azure Boards. If it is empty, no link has been created.
• The branch exists in Azure Repos. A deleted branch will leave a broken Development link.
• The branch was created from this work item (or the link was added manually). Branches that exist in Azure Repos but were never linked to the work item are invisible to BranchDeploy.

BranchDeploy is deploying the wrong branch

If BranchDeploy is picking up a branch you did not expect:

• Check all Development links on the work item. There may be an older branch or merged PR linked alongside the current one.
• On Pro, use the branch picker to see all candidates and select the correct one.
• Remove stale Development links from previous branches that have already been merged.

The PR link shows the wrong branch

BranchDeploy uses the PR's source branch — the branch being merged into the target. If you link a PR that is merging from feature/checkout-flow into main, BranchDeploy will resolve and deploy feature/checkout-flow. This is the correct branch for UAT and staging. If you need to deploy main, queue the pipeline directly without a PR context.