Runtime parameters

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

Runtime parameters let you have more control over what values can be passed to a pipeline. With runtime parameters you can:

• Supply different values to scripts and tasks at runtime
• Control parameter types, allowed ranges, and defaults
• Dynamically select jobs and stages with template expressions

You can specify parameters in templates and in the pipeline. Parameters have data types such as number and string, and they can be restricted to a subset of values. The parameters section in a YAML defines what parameters are available.

Parameters are only available at template parsing time. Parameters are expanded just before the pipeline runs so that values surrounded by ${{ }} are replaced with parameter values. Use variables if you need your values to be more widely available during your pipeline run.

Note

This guidance does not apply to classic pipelines. For parameters in classic pipelines, see Process parameters (classic).

Parameters must contain a name and data type. Parameters can't be optional. A default value needs to be assigned in your YAML file or when you run your pipeline. If you don't assign a default value or set default to false, the first available value is used.

Use templateContext to pass extra properties to stages, steps, and jobs that are used as parameters in a template.

Use parameters in pipelines

Set runtime parameters at the beginning of a YAML.

This example pipeline includes an image parameter with three hosted agents as string options. In the jobs section, the pool value specifies the agent from the parameter used to run the job. The trigger is set to none so that you can select the value of image when you manually trigger your pipeline to run.

parameters:
- name: image
  displayName: Pool Image
  type: string
  default: ubuntu-latest
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest

trigger: none

jobs:
- job: build
  displayName: build
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber) with ${{ parameters.image }}

From the pipeline runs page, select Run pipeline to run the pipeline. You'll see the option to select the Pool Image. If you don't make a selection, the default option, ubuntu-latest gets used. You won't have the option to select a Pool Image if you run your pipeline from the YAML editor.

Use conditionals with parameters

You can also use parameters as part of conditional logic. With conditionals, part of a YAML runs if it meets the if criteria.

Use parameters to determine what steps run

This pipeline adds a second boolean parameter, test, which can be used to control whether or not to run tests in the pipeline. When the value of test is true, the step that outputs Running all the tests runs.

parameters:
- name: image
  displayName: Pool Image
  values:
  - windows-latest
  - ubuntu-latest
  - macOS-latest
- name: test
  displayName: Run Tests?
  type: boolean
  default: false

trigger: none

jobs:
- job: build
  displayName: Build and Test
  pool: 
    vmImage: ${{ parameters.image }}
  steps:
  - script: echo building $(Build.BuildNumber)
  - ${{ if eq(parameters.test, true) }}:
    - script: echo "Running all the tests"

Use parameters to set what configuration is used

You can also use parameters to set which job runs. In this example, different architectures build depending on the value of config parameter, which is a string type. By default, both the x86 and x64 architectures build.

parameters:
- name: configs
  type: string
  default: 'x86,x64'

trigger: none

jobs:
- ${{ if contains(parameters.configs, 'x86') }}:
  - job: x86
    steps:
    - script: echo Building x86...
- ${{ if contains(parameters.configs, 'x64') }}:
  - job: x64
    steps:
    - script: echo Building x64...
- ${{ if contains(parameters.configs, 'arm') }}:
  - job: arm
    steps:
    - script: echo Building arm...

Selectively exclude a stage

You can also use parameters to set whether a stage runs. In this example, there's a pipeline with four stages and different jobs for each stage. The Performance Test stage runs if the parameter runPerfTests is true. The default value of runPerfTests is false so without any updates, only three of the four stages run.

parameters:
- name: runPerfTests
  type: boolean
  default: false

trigger: none

stages:
- stage: Build
  displayName: Build
  jobs:
  - job: Build
    steps:
    - script: echo running Build


- stage: UnitTest
  displayName: Unit Test
  dependsOn: Build
  jobs:
  - job: UnitTest
    steps:
    - script: echo running UnitTest


- ${{ if eq(parameters.runPerfTests, true) }}:
  - stage: PerfTest
    displayName: Performance Test
    dependsOn: Build
    jobs:
    - job: PerfTest
      steps:
      - script: echo running PerfTest


- stage: Deploy
  displayName: Deploy
  dependsOn: UnitTest
  jobs:
  - job: Deploy
    steps:
    - script: echo running UnitTest

Loop through parameters

You can also loop through your string, number, and boolean parameters.

Script

In this example, you loop through parameters and print the name and value of each parameter. There are four different parameters and each represents a different type. myStringName is a single-line string. myMultiString is a multi-line string. myNumber is a number. myBoolean is a boolean value. In the steps section, the script tasks output the key and value of each parameter.

# start.yaml
parameters:
- name: myStringName
  type: string
  default: a string value
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true

steps: 
- ${{ each parameter in parameters }}:
  - script: echo ${{ parameter.Key }} 
  - script: echo ${{ parameter.Value }}

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

PowerShell

In this example, you loop through parameters and print the name and value of each parameter. There are four different parameters and each represents a different type. myStringName is a single-line string. myMultiString is a multi-line string. myNumber is a number. myBoolean is a boolean value. In the steps section, you loop through parameters in a PowerShell task and set each parameter as an environment variable.

# start.yaml

parameters:
- name: myStringName
  type: string
  default: a string value
- name: myMultiString
  type: string
  default: default
  values:
  - default
  - ubuntu
- name: myNumber
  type: number
  default: 2
  values:
  - 1
  - 2
  - 4
  - 8
  - 16
- name: myBoolean
  type: boolean
  default: true

steps: 
  - task: PowerShell@2
    env:
      ${{ each parameter in parameters }}:
        ${{ parameter.Key }}: ${{ parameter.Value }}
    inputs:
      filePath: test_script.ps1
      pwsh: true

# azure-pipeline.yaml
trigger: none

extends:
  template: start.yaml

# test_script.ps1

Write-Host "Hello, World!"
Write-Host $env:myStringName

Check for an empty parameter object

You can use the length() expression to check whether an object parameter has no value.

parameters:
- name: foo
  type: object
  default: []

steps:
- checkout: none
- ${{ if eq(length(parameters.foo), 0) }}:
  - script: echo Foo is empty
    displayName: Foo is empty

Dynamically include a list of steps with the stepList parameter

In this example, the stepList parameter type is used to dynamically include a list of steps in the build process.

• The main pipeline (azure-pipelines.yml) defines two jobs: build and deploy.
• The build job uses a template (build.yml) and passes a list of build tasks using the stepList parameter.
• The build.yml template dynamically includes the steps defined in the build_tasks parameter.

#azure-pipelines.yml

trigger:
- main

jobs:
  - job: build
    displayName: 'Build .NET Core Application'
    pool:
      vmImage: 'ubuntu-latest'

    steps:
      - checkout: self

      - template: build.yml
        parameters:
          build_tasks:
            - task: DotNetCoreCLI@2
              displayName: 'Restore'
              inputs:
                command: 'restore'
                projects: '**/*.csproj'  

            - task: DotNetCoreCLI@2
              displayName: 'Build'
              inputs:
                command: 'build'
                arguments: '--no-restore'
                projects: '**/*.csproj' 

  - job: deploy
    displayName: 'Pack for Azure App Service deployment'
    dependsOn: build
    pool:
      vmImage: 'ubuntu-latest'
    steps:
      - download: current
        artifact: drop

The build.yml template:

• Defines the parameter build_tasks with the stepList type and a default empty list.
• Sets the .NET Core SDK to 6.x.
• Iterates over each step in the build_tasks parameter.
• Executes each step defined in the build_tasks list.

#build.yml

parameters:
  - name: build_tasks
    type: stepList
    default: []

steps:
  - task: UseDotNet@2
    displayName: 'Use .NET Core SDK'
    inputs:
      packageType: 'sdk'
      version: '6.x'

  - ${{ each step in parameters.build_tasks }}:
      - ${{ step }}

  - task: DotNetCoreCLI@2
    displayName: 'Publish'
    inputs:
      command: 'publish'
      arguments: '--configuration Release --output $(Build.ArtifactStagingDirectory)'
      projects: '**/*.csproj'

  - task: PublishBuildArtifacts@1
    displayName: 'Publish Artifact'
    inputs:
      PathtoPublish: '$(Build.ArtifactStagingDirectory)'
      ArtifactName: 'drop'

Parameter data types

Data type	Notes
string	string
number	may be restricted to values:, otherwise any number-like string is accepted
boolean	true or false
object	any YAML structure
step	a single step
stepList	sequence of steps
job	a single job
jobList	sequence of jobs
deployment	a single deployment job
deploymentList	sequence of deployment jobs
stage	a single stage
stageList	sequence of stages

The step, stepList, job, jobList, deployment, deploymentList, stage, and stageList data types all use standard YAML schema format. This example includes string, number, boolean, object, step, and stepList.

parameters:
- name: myString  # Define a parameter named 'myString'
  type: string  # The parameter type is string
  default: a string  # Default value is 'a string'

- name: myMultiString  # Define a parameter named 'myMultiString'
  type: string  # The parameter type is string
  default: default  # Default value is 'default'
  values:  # Allowed values for 'myMultiString'
  - default  
  - ubuntu  

- name: myNumber  # Define a parameter named 'myNumber'
  type: number  # The parameter type is number
  default: 2  # Default value is 2
  values:  # Allowed values for 'myNumber'
  - 1  
  - 2  
  - 4  
  - 8  
  - 16  

- name: myBoolean  # Define a parameter named 'myBoolean'
  type: boolean  # The parameter type is boolean
  default: true  # Default value is true

- name: myObject  # Define a parameter named 'myObject'
  type: object  # The parameter type is object
  default:  # Default value is an object with nested properties
    foo: FOO  # Property 'foo' with value 'FOO'
    bar: BAR  # Property 'bar' with value 'BAR'
    things:  # Property 'things' is a list
    - one  
    - two  
    - three  
    nested:  # Property 'nested' is an object
      one: apple  # Property 'one' with value 'apple'
      two: pear  # Property 'two' with value 'pear'
      count: 3  # Property 'count' with value 3

- name: myStep  # Define a parameter named 'myStep'
  type: step  # The parameter type is step
  default:  # Default value is a step
    script: echo my step 

- name: mySteplist  # Define a parameter named 'mySteplist'
  type: stepList  # The parameter type is stepList
  default:  # Default value is a list of steps
    - script: echo step one  
    - script: echo step two  

trigger: none  

jobs: 
- job: stepList  # Define a job named 'stepList'
  steps: ${{ parameters.mySteplist }}  # Use the steps from the 'mySteplist' parameter

- job: myStep  # Define a job named 'myStep'
  steps:
    - ${{ parameters.myStep }}  # Use the step from the 'myStep' parameter