How to deploy an Azure Repos branch from an Azure Boards work item

Your Azure Boards work item already knows which branch holds the change. When a developer creates a branch from the ticket, or links a pull request to it, Azure DevOps records that relationship in the work item's Development section. Yet to deploy that branch, most teams still copy its name, switch to Azure Pipelines, find the right pipeline, change the branch selector, and queue a run by hand.

This guide walks through the whole path from ticket to queued pipeline run: linking the branch, preparing the pipeline, and deploying from the work item itself. It takes around ten minutes to set up once.

What you need

• Azure DevOps Services (dev.azure.com) with Azure Boards, Azure Repos, and Azure Pipelines in the same organisation.
• A YAML or classic build pipeline that deploys whichever branch it is run on.
• Permission to queue that pipeline for the people who will deploy.
• A project administrator to configure the deploy target once.

Step 1: link the branch to the work item

The deployment source comes from the work item's Development links, so the branch or pull request must be linked there. Pick whichever fits your team:

• Create the branch from the work item. In the Development section, click Create a branch. The link is added automatically.
• Link an existing branch or PR. In the Development section, choose Add link and select the branch or pull request.
• Link from the pull request. Add the work item in the PR's Work items panel.

Commit references such as AB#1482 are useful for traceability, but they do not say which branch to deploy. Make sure a branch or PR is linked. See how to link a work item to a branch or pull request for the full walkthrough.

Step 2: make the pipeline deploy the branch it runs on

The pipeline is the part that actually deploys, so it must deploy the run's source branch rather than a hard-coded one. A minimal YAML pipeline for on-demand deployments looks like this:

trigger: none
pr: none

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self

  - script: |
      echo "Branch:    $(Build.SourceBranch)"
      echo "Work item: $(workItemId)"
    displayName: Show what is being deployed

  - script: ./scripts/deploy.sh staging
    displayName: Deploy to staging

• trigger: none and pr: none stop it running on every push, so deployments only happen on request.
• checkout: self checks out the run's source branch, which is the branch you deploy.
• $(workItemId) is optional. If you want it, add a pipeline variable with that name and tick Let users override this value when running this pipeline.

Before going further, run the pipeline manually once on a feature branch and confirm the log prints that branch. Note the pipeline ID from its URL (definitionId=42 means 42). If you are unsure which number to use, see how to find an Azure Pipeline ID.

Step 3: the manual way to deploy the linked branch

With the link and pipeline in place, you can already deploy by hand:

1. Open the work item and read the branch name in the Development section.
2. Copy the branch name, or open the linked PR to find its source branch.
3. Open Azure Pipelines and find the deployment pipeline.
4. Click Run pipeline and change the branch from the default to the one you copied.
5. Fill in any variables, such as the work item ID.
6. Click Run, then paste the run link back into the ticket or chat.

It works, but it relies on someone copying the right branch every time. The usual failures are the default branch left selected, a similar branch picked from autocomplete, or a PR's target branch used instead of its source. See why manual runs deploy the wrong branch.

Step 4: deploy from the work item with BranchDeploy

BranchDeploy is an Azure DevOps Marketplace extension that does steps 1 to 6 above for you, from the ticket.

Configure it once

1. Install BranchDeploy from the Visual Studio Marketplace into your organisation.
2. Open the project and go to Project Settings → BranchDeploy.
3. Enter the pipeline ID from Step 2 and an environment name such as Staging.
4. Add allowed branch patterns, for example feature/* and bugfix/*.
5. Optionally, set the variable name for the work item ID (workItemId in the YAML above).
6. Click Save all environments.

Deploy from any linked work item

1. Open the work item, for example #1482 Add customer invoice export.
2. Click BranchDeploy in the work item toolbar.
3. BranchDeploy reads the Development links and resolves the branch, for example feature/1482-invoice-export. A linked PR resolves to its source branch.
4. The confirmation step shows the work item, repository, branch, and target environment with its pipeline. Check it and click Deploy.
5. The pipeline is queued with that branch as its source. The run ID and a link to the run appear straight away.

If several branches or pull requests are linked, a picker lists them so you choose the right one. If the branch does not match the allowed patterns, BranchDeploy blocks the deployment before any run is queued.

Step 5: verify the run

Open the run link and check the Show what is being deployed step. Build.SourceBranch should be refs/heads/feature/1482-invoice-export and the work item ID should be 1482. If the branch is right but the deployed code is wrong, look at checkout, artifact, or deployment steps in the YAML rather than the branch selection.

Common problems

"No linked branch or pull request was found"

The work item only has commit links, a branch name in a comment, or nothing at all. Add a branch or PR link in the Development section. The no linked branch found checklist covers the edge cases.

The run is queued but nothing deploys

A YAML condition or branch filter may skip the deploy stage for feature branches. Check condition: blocks that only allow main or release/*.

Permission error when queueing

BranchDeploy queues the run as the signed-in user, so that user needs Queue builds on the pipeline. See how to fix queue build permissions.

The branch is blocked

The resolved branch does not match the environment's allowed patterns. Rename the branch to your convention, or add the pattern if that branch family should be deployable. See branch allowlist patterns.

Frequently asked questions

Can I deploy an Azure Repos branch from an Azure Boards work item without an extension?

Not with a button. Azure Boards shows linked branches and pull requests but has no native action that queues a pipeline for them. Without an extension, you copy the branch into Azure Pipelines by hand or script it with the Azure DevOps CLI or REST API. See ways to run an Azure Pipeline from a work item.

Does BranchDeploy change my pipeline?

No. It queues the pipeline you already have, with the linked branch as the run's source branch and, if configured, a few queue-time variables. Approvals, checks, and YAML conditions still apply.

Which branch is used if a pull request is linked?

The pull request's source branch, never its target. If exactly one PR is linked, it takes priority over any branch links. See how BranchDeploy picks the linked branch.

Does it work with Azure DevOps Server or GitHub repositories?

No. BranchDeploy supports Azure DevOps Services with Azure Repos Git branches and pull requests. GitHub links on a work item are reported as unsupported.

Is it free?

The free plan covers one project with one environment. Pro adds unlimited projects and environments, per-environment branch rules, a deployment audit log, and the Microsoft Teams and AI assistant integrations. See pricing.