Pipeline YAML examples

BranchDeploy queues your pipeline through the Azure DevOps Build Queue API and sets the source branch on the run request. That is the only thing it always does. Your pipeline receives the branch through the standard $(Build.SourceBranch) variable and takes it from there - no YAML changes are required.

Optionally, you can configure BranchDeploy to also pass named queue-time values to the pipeline, such as the target environment or the work item ID. Those names are set in Project Settings -> BranchDeploy -> Pipeline parameters.

BranchDeploy does not currently set Azure Pipelines YAML parameters: / templateParameters. Use pipeline variables for optional BranchDeploy-supplied values, and make those variables settable at queue time if Azure DevOps requires it for your pipeline.

Minimal example

No parameter configuration needed. BranchDeploy queues the pipeline on the linked branch and your pipeline runs as normal.

# azure-pipelines.yml
trigger: none

pool:
  vmImage: ubuntu-latest

steps:
  - script: echo "Deploying branch $(Build.SourceBranch)"
    displayName: Deploy

With environment and work item ID variables

If your pipeline needs to know which environment to target or which ticket triggered the run, use variables and set the matching names in BranchDeploy settings:

• Environment parameter name -> environment
• Environment parameter value -> test
• Work item ID parameter name -> workItemId

# azure-pipelines.yml
trigger: none

pool:
  vmImage: ubuntu-latest

steps:
  - script: echo "Deploying to $(environment) for work item $(workItemId)"
    displayName: Deploy

Important: if Azure DevOps rejects the run with a message about queue-time variables, define the variable on the pipeline and mark it Settable at queue time in the pipeline editor.

BranchDeploy sends only the optional values you configure. If the environment or work item ID fields are blank in your BranchDeploy settings, nothing is sent for those.

Deployment to a named environment

This pattern uses the incoming environment variable as the Azure DevOps environment resource name.

trigger: none

stages:
  - stage: deploy
    displayName: Deploy to $(environment)
    jobs:
      - deployment: deploy
        displayName: Deploy
        environment: $(environment)
        pool:
          vmImage: ubuntu-latest
        strategy:
          runOnce:
            deploy:
              steps:
                - script: |
                    echo "Deploying branch $(Build.SourceBranchName)"
                    echo "Work item: $(workItemId)"
                    echo "Environment: $(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.

trigger: none

pool:
  vmImage: ubuntu-latest

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

  - script: echo "Deploying $(Build.SourceBranchName) to $(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 variable names

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

• Environment parameter name → targetEnvironment
• Work item ID parameter name → ticketId

Then your pipeline can read:

steps:
  - script: echo "Deploying ticket $(ticketId) to $(targetEnvironment)"

Branch name in the pipeline

BranchDeploy passes the branch ref as the sourceBranch value on the build queue 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.

Rejecting unexpected environments

BranchDeploy’s branch allowlist controls which branches can be deployed before the run is queued. If you also want the pipeline to reject unexpected environment values, add a validation step early in the pipeline.

steps:
  - bash: |
      case "$(environment)" in
        test|staging|uat) ;;
        *) echo "Unexpected environment: $(environment)" && exit 1 ;;
      esac
    displayName: Validate environment

Next steps

• Configuration guide — set the pipeline ID and parameter names in BranchDeploy
• Troubleshooting — fix pipeline trigger failures