Azure DevOps pipeline cheatsheet

Developers can go a long time between having to touch CI/CD pipelines, and it then takes a long time to remember what all the quirks are. Also whilst editing existing pipeline definitions, it can be difficult to reason about why steps, stages or jobs were chosen in the first place. I’ve started cataloguing some of the differences between the options and the syntax of common usage patterns.

My first point is a warning: always be explicit and use stages or jobs at the root of the pipeline. This is a rule of thumb, for sequential processes, use stages. For parallel processes, use jobs.

Accessing a variable

Template expression: ${{ variables.VariableName }} or ${{ variables['VariableName'] }}

Macro syntax: $(VariableName)

Accessing a parameter

${{ parameters.ParameterName }}

Conditionally including steps/jobs/stages

- ${{ if parameters.extraJobs }}:
    - job: AdditionalWork
      ... remaining job definition ...

Iterating over an array

- ${{each env in parameters.environments}}:
  - task: AzureCLI@2
    ... remaining task definition ...

Note: unfortunately it is not possible to declare an array as a variable. The workaround is to accept it as a parameter and turn the pipeline into a template.

Extending a template

You can leave all of the work to a template and simply pass the parameters:

trigger: none

pr:
  - main
extends:
  template: path-to-my-template.yml
  parameters:
    environments: [Dev, Stg, Prd]

You can also incorporate a template as a separate job or stage in a pipeline that’s doing other work:

jobs:
- template: path-to-my-template.yml
- job: AnotherNonTemplateJob
  ... remaining job definition ...

Remember that there’ll be difficulties if you have steps: at the root of the pipeline — it should be jobs: or stages:.

Schema

Following is the top-level schema. Stages can be replaced with jobs in which case the stage is implicitly created for you, or steps , in which case the job and stage are implicitly created.

Stages:

Jobs: