YAML Linting

A linter reads your file and reports problems without running anything. It catches wrong indentation, trailing spaces, duplicate keys, and style slips before they cause trouble. Think of it as a spell checker for YAML.

What a Linter Checks

Check	Problem caught
Syntax	Broken structure the parser rejects
Indentation	Inconsistent spacing
Duplicate keys	The same key used twice
Trailing spaces	Invisible spaces at line ends
Line length	Lines wider than a chosen limit
Truthy values	Words like yes and on that older parsers read as booleans

Installing yamllint

pip install yamllint

Run it against one file or a whole folder:

yamllint config.yaml
yamllint .

Reading the Output

config.yaml
  3:1       warning  missing document start "---"  (document-start)
  7:15      error    trailing spaces  (trailing-spaces)
  12:3      error    wrong indentation: expected 4 but found 2  (indentation)

Each line shows the position as line and column, the severity, a message, and the rule name in parentheses. Errors fail the check. Warnings only advise.

The Linting Workflow

  Write YAML --> Run linter --> Read messages --> Fix lines --> Run again
        ^                                                           |
        +-----------------------------------------------------------+

Repeat the cycle until the output is silent. A silent linter means the file meets every enabled rule.

Configuring Rules

Create a file named .yamllint in the project folder. The configuration itself uses YAML.

extends: default

rules:
  line-length:
    max: 120
  indentation:
    spaces: 2
    indent-sequences: true
  document-start: disable
  truthy:
    allowed-values: ["true", "false"]

The first line inherits the default rule set. The rules section adjusts individual checks. A rule can also be switched off with disable.

Ignoring Specific Lines

A comment disables a rule for one line when a justified exception exists:

url: https://example.com/a/very/long/path  # yamllint disable-line rule:line-length

Use exceptions sparingly and explain them in a comment.

Tools for Specific Formats

Tool	Target
kubeconform	Kubernetes manifests
actionlint	GitHub Actions workflows
ansible-lint	Ansible playbooks
docker compose config	Docker Compose files

General linters understand YAML grammar. Format-specific tools understand the meaning of each key, so combine both kinds for thorough checks.

Automating Checks

Run the linter automatically so no one has to remember it. A short GitHub Actions workflow does the job:

name: Lint YAML
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install yamllint
      - run: yamllint .

Editors offer the same help while typing. The YAML extension for VS Code underlines errors instantly, and the yamllint extension shows rule violations in the same panel.

Adoption Tips

• Start with the default rules and loosen the ones that annoy the team.
• Agree on a single indentation width.
• Fix existing warnings in one cleanup commit.
• Treat new warnings as bugs from that day forward.

Common Messages and Fixes

The message about wrong indentation means a line sits at a different depth than the rule expects. Compare it with its neighbors and move it to the matching column. The message about trailing spaces means invisible spaces follow the last character, and the editor setting that trims whitespace on save removes them automatically.

The message about truthy values flags words like yes and on. Replace them with true and false, or quote them when text is intended. The message about duplicate keys needs a manual decision, because the linter cannot know which of the two values you want to keep.

Severity Levels

Rules can raise an error or a warning. Errors return a failing exit code, which stops automated pipelines. Warnings print a message and let the pipeline continue. Promote a warning to an error once the team has cleaned the existing files, and the standard stays strict from that point forward.

Consistent files reduce review time. Reviewers discuss meaning instead of spacing.