Why YAML Indentation Breaks CI Config
Debug YAML CI configuration failures caused by indentation, tabs, nested lists, schema rules and invisible whitespace.
Quick Answer
YAML CI files fail when whitespace changes the data structure, not just the visual layout. A list item under the wrong parent, a tab copied from another editor or a schema key placed at the wrong depth can turn a valid-looking config into a different document.
Example Scenario
A deployment job passes locally but the CI runner says the config is invalid. The edited line looked aligned in a web editor, but one list entry moved from the job steps block to the workflow root. The YAML parser accepted the syntax, then the CI schema rejected the shape.
Step-by-Step Explanation
- Show whitespace and replace tabs with spaces.
- Compare the failing config with the last passing version.
- Check whether the parser error is syntax or schema validation.
- Verify list item depth under jobs, steps, services and environment blocks.
- Run the platform-specific config validator before pushing another change.
What to Check First
Start with the smallest changed block. YAML is indentation-sensitive, so a two-space movement can change a scalar into a mapping value or attach a list item to a different parent. Format the snippet, then use a text diff against the last passing commit.
Do not stop after the YAML parser succeeds. CI systems usually add their own schema rules after parsing. A document can be valid YAML and still invalid for GitHub Actions, GitLab CI, CircleCI, Kubernetes or another platform.
Prevention Checklist
- Keep an editor setting that inserts spaces for YAML.
- Add repository linting for YAML files touched by CI and deployment.
- Validate config against the exact platform schema.
- Avoid mixing copied examples from tools that use different nesting conventions.
Common Mistakes
- Using tabs for alignment.
- Moving a dash without moving its parent key.
- Trusting syntax validation when the platform schema is what failed.
- Letting comments hide the visual boundary between sibling blocks.
FAQ
Can valid YAML still fail CI?
Yes. YAML parsing and CI schema validation are separate checks.
Are tabs allowed?
Tabs are unsafe in indentation-sensitive YAML and should be replaced with spaces.
Why did only one job disappear?
The job may have become nested under another key instead of staying at the expected top-level path.