Tips for Writing YAML Files for GitHub Actions

YAML is very sensitive to spacing, indentation, and formatting. Here are some tips to avoid common issues:

1. Use consistent indentation

   • Always use 2 spaces per level (GitHub Actions doesn’t allow tabs).

   • Example:

      

     

     Wrong indentation will throw a parsing error.

2. Watch out for spaces around colons

   • Correct:

      

     

   • Incorrect (common mistake):

     

      

3. Lists need dashes at the correct level

   • Example:

      

     branches: [main]

     Or, for multiple items:

     

      

4. Environment variables

   • Use env: at the right level. Putting it under steps: instead of jobs: will not work.

   • Example:

     

      

5. Run commands

   • Always indent run: commands under the step name.

   • Multi-line commands can use |:

     

      

6. Check for invisible characters

   • Copy-pasting from Word, email, or some websites can introduce non-breaking spaces.

   • Always use a code editor like VS Code or JetBrains Rider for editing YAML.

7. Validate before pushing

   • You can use online YAML validators or the VS Code YAML extension to catch syntax issues before committing.

Adding these tips will help anyone—especially beginners—avoid the common CI YAML errors that are caused by simple spacing or indentation issues.

Writer: Ravinder Singh

Full Stack Developer

I have 15+ years of experience in commercial software development. I write this blog as a kind of knowledge base for myself. When I read about something interesting or learn anything I will write about it. I think when writing about a topic you concentrate more and therefore have better study results. The second reason why I write this blog is, that I love teaching and I hope that people find their way on here and can benefit from my content.