How to deploy the linked branch from an Azure DevOps work item
If your team links branches and pull requests to Azure DevOps work items, you already have the most reliable answer to "which branch should we deploy for this ticket?" It is written on the ticket, in the Development section, put there by the developer who did the work.
Most teams treat that link as traceability: a record for later. This guide is about using it at deploy time, so the branch that reaches QA, staging, or UAT is the one linked to the ticket rather than one someone typed. It covers how to read the link correctly, the cases that trip teams up, and how to keep links deploy-ready.
Why deploy from the link instead of a typed branch name
A typed or pasted branch name passes through a person on its way to the pipeline. A linked branch does not. That removes the most common causes of wrong-branch deployments:
- The Run pipeline dialog left on
main. - A similar name picked from autocomplete, such as
feature/1482-invoice-exportinstead offeature/1482-invoice-export-v2. - A pull request's target branch copied instead of its source.
- The right branch name in the wrong repository.
A link identifies the repository and the exact ref, so none of these can happen when the deployment reads it directly.
Reading the linked branch by hand
- Open the work item and expand the Development section.
- If a branch is listed, note its name and repository.
- If a pull request is listed, open it and note the source branch (the one being merged), not the target.
- If several are listed, work out which is current: the active PR, or the most recent branch.
- Queue the deployment pipeline on that branch, in the pipeline that deploys that repository.
Steps 3 and 4 are where it goes wrong. They need judgement, and they happen under time pressure.
How BranchDeploy resolves the linked branch
BranchDeploy applies fixed rules to the work item's Development links, so the same ticket always gives the same answer:
| Links on the work item | What gets deployed |
|---|---|
| One branch | That branch. |
| One pull request | The PR's source branch. |
| One pull request plus one or more branches | The PR's source branch. The PR is the clearest signal of the change under review. |
| Several branches, or several pull requests | A picker listing every candidate, with its repository, so the user chooses. |
| Only commits, comments, or GitHub links | Nothing. BranchDeploy stops and explains why, rather than guessing. |
Whatever is resolved is shown in a confirmation step with the work item, repository, branch, and target environment. Then the branch is checked against the environment's allowed branch patterns, and only then is the pipeline queued, with the linked branch as the run's source.
Cases that trip teams up
Stale links from earlier attempts
A ticket that was reopened, or restarted on a new branch, often keeps the old branch or PR link. Links are not removed when a PR is completed or abandoned, so an old link can still be offered as a candidate, or still win if it is the only PR linked. Remove links to branches and PRs that no longer represent the work.
The source branch was deleted
When a PR is completed with "delete source branch" ticked, the link stays but the branch is gone. Deploying it fails in the pipeline because there is nothing to check out. After merge, deploy the target branch through your normal release flow instead.
Work split across repositories
A ticket that touches a frontend and an API repository can have a branch in each. These appear as separate candidates labelled with their repository. Make sure the environment's pipeline deploys the repository you pick, or configure one environment per repository.
Only commits are linked
AB#1482 in a commit message links the commit, not the branch. A commit can live on several branches, so it cannot say which one to deploy. Link the branch or PR as well.
Keeping links deploy-ready
- Create branches from the work item so the link is added automatically.
- Link the pull request to the work item as soon as it is opened.
- One ticket, one active branch or PR, wherever possible.
- Remove stale links when a ticket is restarted on a new branch.
- Use allowed branch patterns such as
feature/*andbugfix/*so an unexpected link cannot reach the environment. See branch allowlist patterns.
Frequently asked questions
Where do I see the branch linked to an Azure DevOps work item?
In the work item's Development section, which lists linked branches, pull requests, and commits with their repository. For how links get there, see how to link a work item to a branch or pull request.
Can I deploy a linked branch without BranchDeploy?
Yes. Read the branch from the Development section and queue the pipeline on it manually, or script it with the REST API by reading the work item's relations. BranchDeploy does the reading and resolving for you and adds a confirmation step. See ways to run an Azure Pipeline from a work item.
What happens if the work item has no linked branch?
BranchDeploy stops with a "no linked branch or pull request" message. It never falls back to a default branch. The no linked branch found checklist covers the usual causes.
Does a linked pull request deploy the merged result?
No. It deploys the PR's source branch as it currently stands, not the PR merge ref used by PR validation builds. See deploy a pull request source branch.
