Events
Take the Microsoft Learn Challenge
Nov 19, 11 PM - Jan 10, 11 PM
Ignite Edition - Build skills in Microsoft Azure and earn a digital badge by January 10!
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
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:
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.
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.
You can also use parameters as part of conditional logic. With conditionals, part of a YAML runs if it meets the if
criteria.
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"
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...
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
You can also loop through your string, number, and boolean parameters.
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
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
In this example, the stepList
parameter type is used to dynamically include a list of steps in the build process.
azure-pipelines.yml
) defines two jobs: build and deploy.build.yml
) and passes a list of build tasks using the stepList
parameter.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:
build_tasks
with the stepList type and a default empty list.build_tasks
parameter.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'
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
Events
Take the Microsoft Learn Challenge
Nov 19, 11 PM - Jan 10, 11 PM
Ignite Edition - Build skills in Microsoft Azure and earn a digital badge by January 10!
Register now