🧭 Pro Tips & Gotchas

What this does

• Strips trailing whitespace from each line and removes trailing blank lines. That is the whole job, and it is the fix for the single most common YAML CI complaint.
• It is intentionally cosmetic: no re-indentation, no key sorting, no quote normalisation.

YAML gotchas that are not cosmetic

• Tabs are illegal as indentation in YAML. One tab anywhere in the indentation makes the parser fail, and many editors will not show it. :meta: with a tab after the colon is a real file people ship.
• yes, no, on, off, y, n, true, false all parse as booleans in YAML 1.1 (which most tooling still uses). A no: key or a on: true value is a footgun; Docker Compose and GitHub Actions have both bitten users here. Quote the string: "no".
• Unquoted version strings lose the patch component: version: 3.0 becomes the float 3, and 1.10 becomes 1.1. Quote versions and semantic versions.
• Leading zeros are octal in YAML 1.1: zip: 012345 silently becomes 5097 in decimal. Same trap for 0755 permissions in a config file.
• A missing space after the colon (key:value) is a parse error, not a style issue — but key : with a trailing space before the colon is legal and reads like a typo.
• Duplicate keys: most parsers take the last value without warning; strict ones error. GitHub Actions and Kubernetes disagree about which applies, so a duplicated env: block can quietly override your secrets.
• <<: anchor merge keys and &anchor/alias reuse are features, not corruption — do not "clean" them out.

For real validation

yamllint (lint rules, line numbers), python -c "import sys,yaml; yaml.safe_load(sys.stdin)" (parse check — and use safe_load, never yaml.load, which can execute arbitrary Python objects), or yq eval to see what the parser actually produced. If a value looks wrong in yq output, it is a quoting problem, not a whitespace one.