Parameters and Variables
There are a lot of topics to cover for YAML-based Pipelines in Azure DevOps. So, I will be breaking this up into a multi-part series. This section will be updated over time with links to the whole series of articles once they are written.
Part 1 - The Basics
Part 2 - Structure of a YAML Pipeline
Part 3 - Pipeline Triggers
Part 4 - Pipeline Resources
Part 5 - Pools and Agents
Part 6 - Parameters and Variables (you're reading it now!)
Part 7 - Stages, Jobs, and Steps
Parameters
Parameters defined at the Pipeline-level are also known as Runtime Parameters. They are called Runtime Parameters because when you run a Pipeline manually, you can interactively change the values of each Parameter. For example, say you created a Parameter called 'env'. The first time you run the Pipeline you could enter a value of 'Prod' for this Parameter. The second time you run the Pipeline you could enter a value of 'Test' for this Parameter. I think you get the idea. The whole point is that you can change values of these Parameters at runtime, and these values can then be used in Pipeline logic to affect how your Pipeline operates.
Defining Parameters
Each Parameter must specify a type. There are the common types such as boolean, number, object, and string. And then there are many different types that deal with various different Pipelines objects, such as environment, filePath, pool, secureFile, serviceConnection, container, containerList, deployment, deploymentList, job, jobList, stage, stageList, step, stepList.
Each Parameter must have a value. There are multiple ways to provide a value for your Parameter:
Provide a default value in the YAML by using the 'default' key as shown below
Run the Pipeline and provide a value manually at runtime
If neither of the above two options are used, then the first value listed in the 'values' key will be used
Using Parameters
There is only one way to use Parameters, and that is Template Expressions. We'll go over Template Expressions later in this post.
Specifying the parameter name can be done using one of two syntaxes. Both are shown in the code below, and both produce the same result.
Variables
There's a lot to cover with variables, so let's jump right in. Variables can be defined at 4 different levels: in the Azure Pipelines web user interface, or in your YAML at the Pipeline-level, Stage-level, or Job-level. UI Variables are the least specific, while Job-level Variables the most specific. More specific Variables take priority or less specific ones.
UI Variables have one unique feature in that they can be marked as 'secret' and therefore will be encrypted. This could be used for Variables that contain sensitive values. UI Variables can also be put into Variable Groups, which can be shared between multiple Pipelines. However, if you'd like to stay with strictly YAML code, and you don't want to do anything manually through a UI, then you could use Variable templates. With this option, you would have all of your Variables in one file, and then you would reference that file from multiple Pipelines.
Defining Variables
Variable names can use only letters, numbers, periods, and underscores. Variable names cannot begin with these reserved words (regardless of capitalization): endpoint, input, path, secret, and securefile. Variables don't use types, as all Variables are stored as strings. There are 2 ways to define variables:
Using Variables
There are 3 different ways you can use Variables: template expressions, runtime expressions, and macro syntax. All 3 will be covered in more detail later in this post. Both template expressions and runtime expressions allow you to define the Variable name using 2 different syntaxes. Both are shown in the code below, and both produce the same result.
Variables are automatically converted to environment variables inside the Pipeline Agent and are available to use within Tasks/Steps. When Pipeline Variables are being converted to environment variables, the Variable names are converted to uppercase, and periods are converted to underscores. The exception is for Variables that are defined in the Web Interface and marked as 'secret'. These will not automatically be converted to environment variables. However, you can still manually map these types of Variables into environment variables by using the 'env' parameter on the Task/Step.
Template & Runtime Expressions, plus Macro Syntax
Template Expressions
Template Expressions are evaluated once at the very beginning of a Pipeline, at compile time. Template Expressions can be used for Parameters, Variables, or Azure DevOps Expressions. If you're using a Template Expression for a Parameter or a Variable, and said Parameter/Variable doesn't exist, then the Template Expression will evaluate to an empty string. Template Expressions can be used anywhere in a YAML statement, in the key (left side) or the value (right side).
Runtime Expressions
Runtime Expressions are evaluated once at the beginning of each job, at runtime. Runtime Expressions are typically used to hold Azure DevOps Expressions and are most often found inside Condition statements. Runtime Expressions are able to expand Variables, but not Parameters. If you're using Runtime Expressions for a Variable, and said Variable doesn't exist, then the Runtime Expression will evaluate to an empty string. In a typical key/value YAML statement, Runtime Expressions can only be used in the value (right side), they cannot be used in the key (left side). Further, Runtime Expressions must make up the entire value (right side) and cannot be combined with anything else.
Macro Syntax
Macro Syntax is evaluated at runtime, once at the beginning of each job, and also at the beginning of every Step/Task. Macro Syntax can be used to expand Variables only. If the Variable doesn't exist, then the entire Macro Syntax will be left as-is. In other words, if the Macro Syntax is $(something) and a Variable called something doesn't exist, then the actual text $(something) will be left as-is. In a typical key/value YAML statement, Macro Syntax can only be used in the value (right side), it cannot be used in the key (left side). Macro Syntax can only be used in certain spots throughout your Pipeline, such as Stages, Jobs, and Steps.
| Template Expressions | Runtime Expressions | Macro Syntax |
Syntax | ${{ ... }} | $[ ... ] | $(...) |
Will expand: | Parameters Variables Expressions | Variables Expressions | Variables |
Processed during: | Compile Time | Runtime | Runtime, before a Task executes |
If var/par doesn't exist? | Empty string | Empty string | $(var) |
Used in: | Keys or Values | Values (*must be the entire value) | Values |
To summarize, we discussed how to define and use Runtime Parameters, how to define and use Variables. We also covered Template Expressions, Runtime Expressions, and Macro Syntax.
Next up, we'll finally be discussing Stages, Jobs, and Steps.