top of page
Search
  • Nathan

Azure DevOps YAML Pipelines - Part 6

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.

 

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.

10 views
bottom of page