Lint and Cleanup
YAML CI Linting Guide
Add YAML lint checks to CI without blocking teams on noisy style rules or leaking environment configuration. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Start with safety rules | Syntax errors, duplicate keys and tabs should fail before style preferences. |
| Scope the paths | Lint workflow, Docker, Kubernetes and config folders separately. |
| Use examples in reviews | A failing lint message should point to a small, teachable config pattern. |
| Tune gradually | Strict style rules are easier to adopt after the team trusts the signal. |
Starter snippet
yamllint .github/workflows docker-compose.yml k8s/
# Fail on syntax and risky structure first.Review checks
- Keep CI lint output short enough to read.
- Document suppressions and why they exist.
- Avoid printing secret-expanded config.
- Run product-specific validation after generic YAML linting.
Common mistakes
- Failing builds on cosmetic style before syntax safety is stable.
- Linting generated files that developers cannot edit.
- Using one config for every repository without context.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Github Actions Debugging Guide, YAML Lint Error, Ci Failing Tests Debugging Guide.