Understanding YAML Indentation in Azure DevOps Pipelines

When working with YAML pipelines in Azure DevOps, indentation isn’t just about readability—it directly defines how your pipeline is interpreted and executed.

Let’s start with a correct and clean YAML structure.

---

✅ Correct Version

variables:
  conn: test

steps:
  - script: echo "Hello565 $(conn)"
    displayName: step1

  - script: echo "Hello"
    displayName: step2

This structure ensures that:

• variables are defined at the root level
• steps is a list
• Each step contains properly aligned properties

---

🧠 How to Think About Spaces

YAML uses spaces to represent hierarchy. Think of it like a tree structure:

steps:                # level 0
  - script: ...       # level 1 (2 spaces)
    displayName: ...  # level 2 (aligned with script)

Key Idea:

• Each level is indented using 2 spaces
• Elements at the same level must be perfectly aligned
• Misalignment changes how YAML is interpreted internally

---

🔁 Alternative: Multiline Script

When your script contains multiple commands, YAML provides a cleaner way using the | operator:

- script: |
    echo "Hello565 $(conn)"
    echo "Another line"
  displayName: step1

Why use |?

• Preserves line breaks
• Makes scripts more readable
• Prevents formatting issues

---

⚠️ Golden Rules for YAML

To avoid common mistakes, follow these rules:

• ✔️ Always use 2 spaces per indentation level
• ❌ Never mix indentation levels randomly
• ✔️ Align keys at the same level exactly
• ✔️ Use | for multiline values like scripts
• ❌ Avoid tabs—only spaces are allowed

---

💡 Final Thought

In YAML, spacing is structure. A small indentation mistake can completely change how your pipeline is parsed and executed. Once you get comfortable with this, writing pipeline definitions in Azure DevOps becomes much more predictable and error-free.