BranchDeploy / Docs /

Pipeline YAML examples

BranchDeploy triggers your Azure Pipeline by calling the Run Pipeline API with a parameters block. Your pipeline YAML needs to declare those parameters for them to be received.

Minimal example

This is the smallest pipeline that works with BranchDeploy’s default parameter names.

# azure-pipelines.yml
parameters:
  - name: environment
    type: string
    default: test

  - name: workItemId
    type: string
    default: ''

trigger: none

pool:
  vmImage: ubuntu-latest

steps:
  - script: echo "Deploying to ${{ parameters.environment }} for work item ${{ parameters.workItemId }}"
    displayName: Deploy

BranchDeploy sends environment and workItemId by default. Change the parameter names in your BranchDeploy configuration if your pipeline uses different names.

Deployment to a named environment

This pattern uses a matrix strategy to map the incoming environment parameter to the correct Azure DevOps environment resource.

parameters:
  - name: environment
    type: string
    values:
      - test
      - staging
    default: test

  - name: workItemId
    type: string
    default: ''

trigger: none

stages:
  - stage: deploy
    displayName: Deploy to ${{ parameters.environment }}
    jobs:
      - deployment: deploy
        displayName: Deploy
        environment: ${{ parameters.environment }}
        pool:
          vmImage: ubuntu-latest
        strategy:
          runOnce:
            deploy:
              steps:
                - script: |
                    echo "Deploying branch $(Build.SourceBranchName)"
                    echo "Work item: ${{ parameters.workItemId }}"
                    echo "Environment: ${{ parameters.environment }}"
                  displayName: Deploy steps

Using workItemId to tag the run

You can use the work item ID to tag the pipeline run so that you can trace a deployment back to its originating ticket.

parameters:
  - name: environment
    type: string
    default: test

  - name: workItemId
    type: string
    default: ''

trigger: none

pool:
  vmImage: ubuntu-latest

variables:
  buildName: ${{ format('WI-{0} — {1}', parameters.workItemId, parameters.environment) }}

steps:
  - bash: echo "##vso[build.updatebuildnumber]$(buildName)"
    displayName: Set build name

  - script: echo "Deploying $(Build.SourceBranchName) to ${{ parameters.environment }}"
    displayName: Deploy

This sets the pipeline run name to something like WI-4217 — test so you can see at a glance which ticket triggered which run.

Custom parameter names

If your pipeline already uses different parameter names, configure BranchDeploy to match. In Project Settings → BranchDeploy, set:

Then your pipeline can declare:

parameters:
  - name: targetEnvironment
    type: string
    default: test

  - name: ticketId
    type: string
    default: ''

Branch name in the pipeline

BranchDeploy passes the branch ref as the sourceBranch override on the run request. You can access it inside the pipeline as the standard Azure Pipelines variable:

steps:
  - script: echo "Branch: $(Build.SourceBranch)"
    displayName: Show branch

This will print the full ref name such as refs/heads/feature/my-branch.

Restricting which environments are accepted

Use values: to prevent BranchDeploy from triggering with an unexpected environment value. Passing an unlisted value causes the pipeline to fail at queue time.

parameters:
  - name: environment
    type: string
    values:
      - test
      - staging
      - uat

Next steps