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.

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 parameters

Azure Pipelines supports runtime parameters that let you pass values when a run is triggered. If your pipeline is configured to accept a branch name and environment name as parameters, you can make branch-specific deployments more repeatable.

Example pipeline YAML with runtime parameters:

parameters:
  - name: branchName
    displayName: Branch to deploy
    type: string
    default: main
  - name: environment
    displayName: Target environment
    type: string
    default: staging

trigger: none

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    ref: ${{ parameters.branchName }}
  - script: echo "Deploying ${{ parameters.branchName }} to ${{ parameters.environment }}"

With parameters defined, users can select the branch and environment from the Run pipeline dialog. This reduces the risk of wrong-branch errors but still requires the user to open the pipeline UI and enter the values manually.

BranchDeploy can work with this pattern. When configured with matching parameter names, it passes the resolved branch name and environment name directly to the pipeline — no manual entry required.

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, passing the branch name and environment name as parameters.

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. Check pipeline permissions under Project Settings → Pipelines → [pipeline name] → Security.

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.

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 branch parameter name and environment parameter name to match your pipeline's expected input names.
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.