How to deploy a specific Azure Repos branch with Azure Pipelines

Deploying a specific Azure Repos branch to a staging or UAT environment with Azure Pipelines is one of the most common tasks in a feature-branch development workflow. It is also one of the most error-prone — the branch has to be identified correctly, the right pipeline has to be selected, and any environment-specific parameters have to be filled in manually.

This guide covers three options for deploying a specific branch, their trade-offs, common pitfalls, and a recommended team workflow.

Quick comparison

Why branch-specific deployments matter

When a team works with feature branches, different features are developed in parallel and need to be tested independently before merging to a shared branch. This means each deployment to a QA, staging, or UAT environment needs to target a specific branch — not just the main branch or a fixed release tag.

Without a reliable way to deploy specific branches, teams either:

• Deploy everything to a shared environment, creating conflicts when multiple features need testing at the same time.
• Wait for a merge to deploy, which slows down the feedback loop between development and testing.
• Create complex pipeline branch filter logic that is hard to maintain.

A clean branch-deployment workflow lets each ticket, pull request, or feature be deployed and tested in isolation.

Option 1: manual pipeline run with a selected branch

The most direct way to deploy a specific Azure Repos branch is to trigger a manual pipeline run and select the branch when you start the run.

Steps:

1. Open Azure Pipelines in your Azure DevOps project.
2. Select the pipeline you use for staging, UAT, or the target environment.
3. Click Run pipeline.
4. In the branch selector, type or select the branch you want to deploy.
5. Add any environment or parameter values if the pipeline expects them.
6. Click Run.

This works, but it requires the user to know which pipeline to open, which branch to select, and which parameter values to use. For QA engineers or delivery managers who are less familiar with the pipeline structure, this is friction.

Option 2: environment and work item variables

Azure Pipelines supports queue-time values that let you pass context when a run is triggered. The branch should usually be selected as the run's source branch; environment and work item values can be passed as variables when the pipeline starts.

Example pipeline YAML using the selected source branch and an environment variable:

trigger: none

pool:
  vmImage: ubuntu-latest

steps:
  - script: |
      echo "Deploying $(Build.SourceBranch)"
      echo "Target environment: $(environment)"

With this pattern, users select the branch in the Run pipeline dialog and provide any environment value your pipeline expects. This reduces wrong-branch errors but still requires the user to open the pipeline UI and enter values manually.

BranchDeploy automates the same idea. It sets the resolved linked branch as the pipeline run's source branch, then optionally passes environment and work item ID values using the names configured in Project Settings — no manual branch entry required.

For a deeper explanation, see Azure Pipelines queue-time variables and parameters.

Option 3: linked work item branch deployment with BranchDeploy

BranchDeploy is an Azure DevOps Marketplace extension that adds a deploy action to Azure Boards work items. It resolves the Azure Repos branch linked to the work item and queues your configured pipeline with that branch set as the run source. If configured, it also passes environment and work item ID values to the pipeline.

The user never types a branch name. BranchDeploy reads the Development links on the work item, confirms the branch and environment with the user, and queues the pipeline run.

This approach is particularly useful when:

• Your team links Azure Repos branches or pull requests to work items as part of normal development workflow.
• QA engineers deploy features for testing and should not need to know the branch name or pipeline structure.
• You want to keep deployment decisions traceable to specific tickets.

See how to deploy an Azure Pipeline from a work item for the full flow.

Common pitfalls

Regardless of which approach you use, the following pitfalls affect branch-specific deployments in Azure Pipelines.

Pipeline branch filters

Azure Pipelines YAML can include branch filters on triggers and stages. If your pipeline has a branch filter that only allows main or specific release branches, a manual run for a feature branch may be blocked or may not execute certain stages. Review your pipeline's trigger and condition blocks before expecting a feature branch run to complete the full deployment.

User lacks queue permission

Azure Pipelines respects queue-build permissions per pipeline. If the user triggering the deployment does not have permission to queue the pipeline manually, they will not be able to deploy — regardless of whether they are using BranchDeploy or the Azure Pipelines UI. See how to fix Azure DevOps queue build permissions.

Wrong default branch selected

When a user clicks Run pipeline, the branch selector defaults to the pipeline's default branch (often main). If the user does not change the branch, the wrong code is deployed. This is one of the most common causes of "QA deployed the wrong thing" incidents. BranchDeploy's confirmation step shows the resolved branch before queuing, which makes this error visible before it happens. See why manual runs deploy the wrong branch for a troubleshooting checklist.

Environment parameter mismatch

If your pipeline expects an environment parameter named targetEnvironment but BranchDeploy is configured to pass it as environment, the parameter will be ignored and the pipeline may use its default value. Configure BranchDeploy parameter names in Project Settings to match your pipeline's parameter names exactly.

Work item has no linked branch or PR

BranchDeploy reads Development links from the work item. If a branch exists in Azure Repos but has not been linked to the work item through the Development section, BranchDeploy cannot resolve it. Developers should create branches from work items (which auto-links them) or manually add Development links.

PR source branch differs from target branch

When a pull request is linked to a work item, BranchDeploy deploys the PR's source branch — the feature branch being merged — not the target branch (typically main or develop). This is usually the correct behaviour for UAT and staging, but is worth being explicit about in your team's workflow.

Recommended team workflow

For teams using Azure Boards, Azure Repos, and Azure Pipelines together, the most reliable branch-deployment workflow is:

1. Create branches from work items. This automatically adds a Development link on the work item and gives the branch a consistent name. See how to link a work item to a branch or PR.
2. Configure one deployment pipeline per environment. Keep your staging pipeline separate from your UAT pipeline. BranchDeploy supports configuring multiple environments (Pro) or a single environment (Free).
3. Configure BranchDeploy with matching parameter names. Set the environment and work item ID parameter names only if your pipeline expects those values. BranchDeploy sets the branch as the run source automatically.
4. Let QA deploy from the work item. With BranchDeploy installed, QA engineers can open the linked work item, click the deploy action, confirm the branch and environment, and queue the pipeline without ever touching Azure Pipelines directly.
5. Use branch allowlists to prevent accidents. Configure glob patterns such as feature/* and bugfix/* to prevent main or release branches from being accidentally deployed to non-production environments.

This workflow gives developers speed, gives QA independence, and gives delivery teams traceability — all from the work item where the feature was planned.