Azure-devops-docs: "Each" and "If" syntax clarifications

[JustinGrote]

A few things that should be pointed out on this page so that others don't have to suffer through the obtuse error messages and trial-and-error that I did:

1. You must have the trailing colon (:) after the expression or it will fail with a parse error
2. You must include the leading '-' if what you are trying to substitute or conditionalize is a sequence entry. Omit it if you are just trying to add a mapping value
3. If it is a sequence entry, you can do the whole sequence and insert variables as required
4. You can nest multiple each statements, indenting them a level after each. IF you do this, it will create a "matrix" of all possible combinations, a good substitute for how matrix functionality works in Github Actions.
5. Whatever comes after the each or if statement must be indented one level, even if it doesn't line up with the rest of the sequence/map.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 6724abea-bbdc-bf66-ed5e-3214fa6c3e66
• Version Independent ID: 4f8dab21-3f0e-da32-cc0e-1d85c13c0065
• Content: Templates - Azure Pipelines
• Content Source: docs/pipelines/process/templates.md
• Product: devops
• Technology: devops-cicd
• GitHub Login: @juliakm
• Microsoft Alias: jukullam

[Slooz]

I believe everything that you said is already reflected in the examples.

[JustinGrote]

@Slooz but it's not explicit, it took a ton of trial and error to find what the syntax was for a map vs. a sequence. As this is documentation it should provide guidance.

If examples were enough, you would just publish the raw YAML reference and say "there you go, here's the documentation" :)

EDIT: Also because it is "special" nonintuitive YAML syntax that doesn't follow the normal rules regarding indentation and whatnot, it should be explicity documented.

[PirateBread]

You should definitely provide the input values for the example code, so people can understand the syntax expected.
For example, the datatype StepList or JobList , all MS examples just show [].

I dare you to find me some documentation that actually shows an example of the syntax for either of those data types. It's much easier if you just point it out, however stupid and obvious you think it might be.

Same with all the stuff you are doing iterating through parameters etc.. It's 10x easier for someone to understand if you show actual real examples instead of this stripped down rubbish.

[paulmarshall]

Nope. I can't get a conditional template to work.

This:
`jobs:

• job: Scan
  condition: eq(variables['toggle.build.ahe'], 'true')
  steps:
  
  
  
  • ${{ if eq(variables['toggle.build.ahe'], 'true') }}:
  
  
  • template: build-scan-tasks.yml
    
    `
    
    Results in the job being run but with no tasks. And yes, the variable is set to 'true'.
  
  

[Slooz]

@paulmarshall, Is this what you want?
```yaml
jobs:
${{ if eq(variables['toggle.build.ahe'], 'true') }}:
- job: Scan
steps:
- template: build-scan-tasks.yml

[Slooz]

You should definitely provide the input values for the example code, so people can understand the syntax expected.
For example, the datatype StepList or JobList , all MS examples just show [].

I dare you to find me some documentation that actually shows an example of the syntax for either of those data types. It's much easier if you just point it out, however stupid and obvious you think it might be.

Same with all the stuff you are doing iterating through parameters etc.. It's 10x easier for someone to understand if you show actual real examples instead of this stripped down rubbish.

@PirateBread the syntax is the same as for creating any other stage/job/step.

[PirateBread]

@Slooz thank you I finally worked it out with the help of this thread and banging my head against the commit tree until all the errors went away.

I wonder if you can help point out where I am going wrong:

 parameters:
 - name: modules
   type: object
   default:
     terraform: ["v0.1.0", "v0.1.1"]

 steps:
 - ${{ each repository in parameters.modules }}:
   - ${{ each repo in repository }}:
     - ${{ each tag in repository.value }}:
       - checkout: git://nostromo/${{ repository.key }}@refs/tags/${{ tag }}
 - checkout: self
 - script: tree

What I want to achieve is a checkout step for each tag.
Which is working in this example but instead of getting 2 checkouts, I'm getting 4

So I'm guessing my middle loop is maybe broken and therefore counting more than it should but I'm stuck and not sure.

[Slooz]

@PirateBread I'm confused by your middle loop, I don't think you need it. Can you try the following?
```yaml
parameters:

• name: modules
  type: object
  default:
  terraform: ["v0.1.0", "v0.1.1"]
  steps:
• ${{ each repository in parameters.modules }}:
  
  
  
  • ${{ each tag in repository.value }}:
    
    
    
    
    
    • bash: echo git://nostromo/${{ repository.key }}@refs/tags/${{ tag }}
    
    
    
  
  
• checkout: self
• script: tree

[PirateBread]

@Slooz - Thanks friend. Yeah that works perfectly..... I'm not sure what I was trying to do with the middle loop. Makes sense that I only need two loops, one for each tag and then an outer loop for each repo.

[VerdonTrigance]

Definitely yaml syntax is not obvious in any point of view. I struggling every time I edit my build template. I doing just as blind because here is no any document that do real help with understanding complex examples. I really hate yaml builds! I have to push tons of useless commits to check if it's work or not! Microsoft give us excessively documentation please.

[VerdonTrigance]

It would be great if user had possibility to "compile" yaml on-premise without having to push changes and watch whole yaml and then check generated file for errors.

[JustinGrote]

It would be great if user had possibility to "compile" yaml on-premise without having to push changes and watch whole yaml and then check generated file for errors.

@VerdonTrigance the vscode azure-pipelines extension does some client-side syntax error checking. There is also the test API that, while requires submitting online to Azure Devops, will check your syntax is correct and expand the variables/loops/etc without actually doing a run.

[VerdonTrigance]

It would be great if user had possibility to "compile" yaml on-premise without having to push changes and watch whole yaml and then check generated file for errors.

@VerdonTrigance the vscode azure-pipelines extension does some client-side syntax error checking. There is also the test API that, while requires submitting online to Azure Devops, will check your syntax is correct and expand the variables/loops/etc without actually doing a run.

Actually it doesn't. I use VSCode right now and that extension is nothing when you working with templates and variables.
Talking about API - what do you mean?

Anyway, today we have no opportunity to 'compile' and understand where the error is.

[JustinGrote]

@VerdonTrigance
https://github.com/microsoft/azure-pipelines-yaml/issues/34#issuecomment-584253286

Implementation as a powershell cmdlet:
https://github.com/DarqueWarrior/vsteam/blob/41c30c5cc8fa53e8fbab87e702a30f4bb629c2ce/.docs/Test-VSTeamYamlPipeline.md

And as mentioned in that thread, no plans to deliver a client-side equivalent (too much work)

[VerdonTrigance]

@VerdonTrigance
microsoft/azure-pipelines-yaml#34 (comment)

Implementation as a powershell cmdlet:
https://github.com/DarqueWarrior/vsteam/blob/41c30c5cc8fa53e8fbab87e702a30f4bb629c2ce/.docs/Test-VSTeamYamlPipeline.md

And as mentioned in that thread, no plans to deliver a client-side equivalent (too much work)

They also mentioned it cannot check templates which mostly cause problems.

[JustinGrote]

@VerdonTrigance
microsoft/azure-pipelines-yaml#34 (comment)
Implementation as a powershell cmdlet:
https://github.com/DarqueWarrior/vsteam/blob/41c30c5cc8fa53e8fbab87e702a30f4bb629c2ce/.docs/Test-VSTeamYamlPipeline.md
And as mentioned in that thread, no plans to deliver a client-side equivalent (too much work)

They also mentioned it cannot check templates which mostly cause problems.

In terms of multi-file templates, yes. You can still reference templates in the same file and expand the whole thing out. I agree it's a big limitation (if you look it's me who called it out) but it's the best we have for now.

Right now when testing templates my best feedback loop is that I set up a custom branch on my repository and have a watcher powershell script that when I save the file, it git pushes it and then watches and pulls the API result, including the full expanded version that shows up in the detail, and reports errors into my Problems tray in vscode. That's as good as it's going to get unless they release a local validator.

[SebastianSchuetze]

@JustinGrote have you seen that you can go to the YAML editor on Azure DevOps and make a check. It seems to validate also the whole nested template structure and tries to generate the full YAML. Haven't checked the API yet. Could it be that this is working now?