Azure Pipelines queue-time variables and parameters

Azure Pipelines can receive values when a run is queued. Those values are useful for deployment workflows because the same pipeline may need to know which branch, environment, or work item triggered the run.

The confusing part is terminology. Azure Pipelines has variables, runtime parameters, predefined build variables, and REST API fields. They are related, but they are not interchangeable.

Short version

• Use the run's source branch for the code you want to deploy.
• Use variables for extra values that scripts read as $(environment) or $(workItemId).
• Use YAML runtime parameters when you need typed values, allowed values, or compile-time template behavior.
• BranchDeploy sets the source branch on the queued run and can pass optional queue-time variables. It does not currently set YAML parameters: / templateParameters.

Variables vs YAML runtime parameters

Queue-time variable example

This pipeline does not need YAML parameter declarations. It reads the source branch from Azure Pipelines and optional queue-time variables by name.

trigger: none

pool:
  vmImage: ubuntu-latest

steps:
  - script: |
      echo "Branch: $(Build.SourceBranch)"
      echo "Environment: $(environment)"
      echo "Work item: $(workItemId)"
    displayName: Show deployment context

In BranchDeploy, set the matching names in Project Settings -> BranchDeploy -> Pipeline parameters:

• Environment parameter name: environment
• Work item ID parameter name: workItemId

Then BranchDeploy can queue the pipeline on the linked branch and pass those optional values if configured.

Runtime parameter example

Runtime parameters are defined in YAML and evaluated before the run starts. They are useful when you need a constrained list of allowed values or when template logic depends on the selected value.

trigger: none

parameters:
  - name: targetEnvironment
    type: string
    default: uat
    values:
      - qa
      - staging
      - uat

steps:
  - script: echo "Deploying to ${{ parameters.targetEnvironment }}"

For a manual run, Azure Pipelines shows these parameters in the Run pipeline dialog. From the CLI, you pass them with --parameters:

az pipelines run \
  --org https://dev.azure.com/YOUR_ORG \
  --project "YOUR_PROJECT" \
  --id 42 \
  --branch feature/checkout-flow \
  --parameters targetEnvironment=uat

Use this pattern when your pipeline design depends on YAML parameters. Use BranchDeploy's optional variables when you want work item context passed into scripts or tasks.

Manual CLI run with variables

For comparison, this CLI command queues a pipeline on a specific branch and passes queue-time variables:

az pipelines run \
  --org https://dev.azure.com/YOUR_ORG \
  --project "YOUR_PROJECT" \
  --id 42 \
  --branch feature/checkout-flow \
  --variables environment=uat workItemId=1234

This is close to the model BranchDeploy automates from the work item: resolve the branch, queue the pipeline, and attach context values without asking the user to type them.

REST API shape

In the Run Pipeline REST API, the branch is set as the repository ref and variables are sent separately.

{
  "resources": {
    "repositories": {
      "self": {
        "refName": "refs/heads/feature/checkout-flow"
      }
    }
  },
  "variables": {
    "environment": { "value": "uat" },
    "workItemId": { "value": "1234" }
  }
}

BranchDeploy's current extension workflow queues through the Azure DevOps Build Queue API rather than the newer Run Pipeline API, but the same design principle applies: branch selection and queue-time context are separate concerns.

Common problems

The variable is blank inside the pipeline

Check the variable name in BranchDeploy settings and in YAML. targetEnvironment, environment, and Environment are different names in practice because your scripts read the exact macro you write.

Azure DevOps rejects the run

Some Azure DevOps organisations restrict variables that can be set at queue time. If you see an error about queue-time variables, define the variable on the pipeline and mark it settable at queue time, or adjust the organisation setting that limits queue-time variables.

The branch is wrong even though the variable is right

The branch is not a queue-time variable in BranchDeploy. It is the run source branch. Check the work item's Development links and the confirmation step to make sure the right branch or PR source branch was resolved.

The pipeline uses YAML parameters only

BranchDeploy will still set the run's source branch, but it will not fill YAML parameters:. If a parameter is required, give it a safe default or adapt the pipeline to read BranchDeploy-supplied values from variables.

Recommended BranchDeploy pattern

1. Let BranchDeploy set the run source branch from the linked work item branch or PR.
2. Use $(Build.SourceBranch) or $(Build.SourceBranchName) inside the pipeline.
3. Use optional variables such as $(environment) and $(workItemId) for deployment context.
4. Keep variable names identical between BranchDeploy settings and YAML.
5. Validate environment values early in the pipeline if the same pipeline can deploy to more than one target.

Official Azure DevOps references

• Runtime parameters
• Azure Pipelines predefined variables
• Run Pipeline REST API