YAML Formatting and Linting¶

Introduction¶

Our project uses YAML files extensively for configuration, GitHub Actions workflows, and issue templates. To ensure consistent formatting and catch syntax/style issues early, we use yamlfmt for formatting and yamllint for validation.

Key Benefits:

✅ Separated responsibilities: yamlfmt formats YAML and yamllint catches syntax/style issues.
🎨 Automatic Formatting: Consistent YAML style across all files
🚀 Fast Performance: Go-based tool for speed and reliability
🔧 Highly Configurable: Customizable rules via .yamlfmt configuration
🤖 Pre-commit Integration: Runs automatically on every commit
💻 No Node.js Required: Pure Go binary, simpler dependency management
🛡️ GitHub Actions Compatible: Tested with workflow files

⚙️ Getting Started¶

Prerequisites¶

Install Go and yamlfmt:

# Install Go (if not already installed)
just install-go

# Install yamlfmt
just install-yamlfmt

Usage¶

Format all YAML files:¶

just format-yaml

Automatically fixes formatting in all .yml and .yaml files

Check for YAML lint issues:¶

just lint-yaml

Shows detailed output of any lint problems

Verify formatting is clean:¶

just check-yaml

Quick pass/fail lint check with success message

🛠 Configuration¶

yamlfmt Configuration (`.yamlfmt`)¶

yamllint Configuration (`.yamllint`)¶

🔄 Pre-commit Integration¶

YAML formatting runs automatically on every commit via pre-commit:

The yamlfmt hook formats .yaml and .yml files automatically.
The yamllint hook validates .yaml and .yml files automatically.
Prevents commits with YAML syntax/style errors.
Ensures codebase consistency and reduces manual reviews.

Example .pre-commit-config.yaml snippet for YAML linting:

repos:
  - repo: https://github.com/google/yamlfmt
    rev: v0.13.0
    hooks:
      - id: yamlfmt
        name: "Format YAML files"
        files: \.ya?ml$
  - repo: local
    hooks:
      - id: yamllint
        name: Lint YAML files
        entry: uvx yamllint -c .yamllint .
        language: system
        pass_filenames: false

🛑 Disabling or Skipping YAML Linting¶

To skip linting temporarily, use the --no-verify flag on git commit.
To disable formatting rules, edit .yamlfmt.
To disable lint rules, edit .yamllint.
To remove linting completely, remove related pre-commit hooks and just commands.