Azure DevOps UAT deployment workflow
A good UAT workflow answers three questions without making people chase context across tools: which ticket is ready, which branch contains the change, and which pipeline run deployed it to the test environment.
Azure Boards, Azure Repos, and Azure Pipelines contain all of that information. BranchDeploy connects it at the work item level so a user can deploy the linked branch from the ticket being tested.
Recommended workflow
- A developer creates a branch from the Azure Boards work item.
- The branch is linked automatically in the work item's Development section.
- The developer opens a pull request and links it to the same work item.
- When the ticket is ready for QA or UAT, the tester opens the work item.
- The tester clicks the BranchDeploy action, confirms the branch and environment, and queues the configured Azure Pipeline.
- Azure Pipelines deploys the branch to UAT.
- The team uses the pipeline run URL and work item context to track what was deployed.
The important part is step 5. QA does not need to know the branch name, find the right pipeline, or ask a developer to queue a run. They start from the ticket they are about to test, and the confirmation step shows the work item, repository, branch, and target environment before anything runs.
Roles and responsibilities
| Role | Responsibility |
|---|---|
| Developer | Create or link the branch, keep the PR linked, and fix deployment failures in the branch. |
| QA tester | Deploy the linked branch to UAT and test the work item against the deployed environment. |
| Delivery manager | Track which work items are deployed, blocked, or ready for acceptance. |
| Project admin | Configure BranchDeploy with the pipeline ID, environment, branch allowlist, and optional variables. |
Pipeline design
The UAT pipeline should be able to run manually on a selected branch. BranchDeploy then automates the branch selection from the linked work item.
A clean UAT pipeline usually has:
trigger: noneif UAT deployments should only happen on request.- A deployment stage that reads the branch from
$(Build.SourceBranch). - Optional variables such as
$(environment)and$(workItemId). - Environment approvals or checks if UAT requires explicit approval before deployment.
- Logging that prints the branch and work item ID at the start of the run.
Branch rules
Most UAT teams should allow feature and bugfix branches, and only allow release branches if the environment is also used for release candidate validation.
feature/*
bugfix/*
release/*Keep main out of the allowlist unless deploying main to UAT is an explicit part of your workflow.
Status flow in Azure Boards
A simple board status flow works well:
- Active: branch exists and work is in progress.
- Ready for QA: PR is open or code is ready to deploy.
- In QA: BranchDeploy has queued a UAT run and testing is underway.
- Accepted: QA or product owner accepts the deployed change.
- Done: branch is merged and deployment path moves to the normal release flow.
BranchDeploy does not force a board process. The key is that a tester can deploy from the work item at the point the ticket enters QA or UAT.
Common failure points
No linked branch
The work item was moved to QA, but no branch or PR is linked in the Development section. Fix the link before asking QA to deploy.
Wrong pipeline ID
The configured pipeline ID points to a CI build or old deployment pipeline. Verify the ID from the Azure Pipelines URL or CLI.
Queue permission missing
The tester can open the work item but cannot queue the UAT pipeline. Grant queue permission to the QA group on the target pipeline.
Environment variable mismatch
The pipeline expects targetEnvironment but BranchDeploy sends environment. Align the variable names in BranchDeploy settings and YAML.
Set up this workflow with BranchDeploy
- Install BranchDeploy from the Visual Studio Marketplace into your Azure DevOps organisation.
- Make sure the UAT pipeline can run manually on a selected branch (
trigger: noneworks well). - In Project Settings → BranchDeploy, enter the UAT pipeline ID, name the environment
UAT, and add allowed branch patterns such asfeature/*andbugfix/*. - Grant the QA group permission to queue the UAT pipeline.
- Ask a tester to open a linked work item and click BranchDeploy.
The free plan covers one project with one environment, which is enough for a single UAT target. Pro adds more environments (for example staging, UAT, and pre-production as separate targets), separate branch rules per environment, and a deployment audit log.
For the details, see BranchDeploy setup and Pipeline YAML examples.
Frequently asked questions
Can QA deploy to UAT without access to Azure Pipelines?
They need permission to queue the UAT pipeline, because BranchDeploy queues runs as the signed-in Azure DevOps user. They do not need to open Azure Pipelines or know which pipeline to use; the deploy starts from the work item.
How do we stop untested branches reaching UAT?
Use a branch allowlist so only the branch families you test, such as feature/* and bugfix/*, can deploy. Add Azure Pipelines environment approvals if UAT also needs a sign-off before each run.
What if two testers need different branches in UAT at the same time?
A single shared UAT environment can only run one branch at a time, whatever tool queues it. Either agree a short queue in the board's "In QA" column, or add more test environments and configure each one in BranchDeploy.
How do we know what is currently deployed to UAT?
Azure Pipelines run history shows the source branch of each run. BranchDeploy Pro also keeps an audit log of who deployed which work item and branch, and whether the run succeeded.
