Check YAML script

Repository-wide lint and validate.

The Sphere includes a helper script check-yaml-v11.sh to recursively find YAML files across all git repos under a root folder and:

• Parse-check them with yq
• Lint with yamllint
• (Optionally) validate Kubernetes manifests with kubeconform
• Offer interactive or auto-fix formatting via yamlfmt (preferred), prettier, or a fallback yq pretty-print
• Be SOPS-aware (skip schema checks and relax lint rules for encrypted files)
• Skip machine-generated files that contain “DO NOT EDIT” (case-insensitive)

Default search root: $HOME/Projects. Pass a directory as the first non-flag argument to target a different root.

Requirements

• yq, yamllint (required)
• kubeconform (optional, for K8s schema checks)
• yamlfmt (preferred), or prettier (fallback) for auto-fixing

Install with Homebrew (if not already):

brew install yq yamllint kubeconform yamlfmt

---

Usage

# Basic (report-only):
./check-yaml-v11.sh

# Interactive fixes for a single repo tree:
./check-yaml-v11.sh ~/Projects/my-repo -i

# Auto-fix all without prompting:
./check-yaml-v11.sh ~/Projects -A

# Disable Kubernetes schema checks entirely:
./check-yaml-v11.sh --no-k8s

# Treat “DO NOT EDIT” files as normal (don’t skip):
./check-yaml-v11.sh --do-not-edit-off

# Skip SOPS files completely (parse, lint, kubeconform):
./check-yaml-v11.sh --skip-sops-all

# Skip SOPS lint only (still parse; kubeconform is skipped by default for SOPS):
./check-yaml-v11.sh --skip-sops-lint

# Disable special SOPS handling (treat as plain YAML):
./check-yaml-v11.sh --sops-off

# Insert a leading '---' where missing (and show it in diff/auto-fix)
./check-yaml-v11.sh --fix-doc-start

# Use a custom yamllint config (overrides relaxed SOPS lint rules):
./check-yaml-v11.sh --yamllint-config ~/.config/yamllint/config

Flags

Flag	Description
-h, --help	Show help and exit
-V, --version	Print script version and exit
-i, --interactive	Prompt to fix each file (y=fix, n=skip, a=fix all, N=fix none, d=show diff, q=quit)
-A, --fix-all	Auto-fix all lint issues (no prompts)
--no-k8s	Disable kubeconform schema validation
--yamllint-config <path>	Use a custom yamllint config file
--fix-doc-start	Auto-insert --- when the document start is missing
--do-not-edit-off	Do not skip files containing “DO NOT EDIT”
--sops-off	Treat SOPS files like normal (no special handling)
--skip-sops-lint	Skip yamllint for SOPS files
--skip-sops-all	Skip all checks for SOPS files (parse, lint, kubeconform)

Behaviour details

• SOPS detection: a file is considered SOPS-managed if it contains a top‑level key sops:. By default, kubeconform is skipped and yamllint runs with relaxed line-length to avoid noise from encrypted blobs. Use the flags above to change this.
• “DO NOT EDIT”: any file containing the phrase (any case, allows spaces) is skipped from all checks by default. Toggle with --do-not-edit-off.
• Interactive diff: choosing d shows a preview of what the formatter would change. Add --fix-doc-start to preview/document-start insertions.
• Auto-fix pipeline: yamlfmt → prettier → yq pretty‑print (as last resort; may drop comments).
• Kubernetes schemas: run kubeconform in strict mode and ignore missing CRD schemas with --ignore-missing-schemas (the script already passes that for broad scans). Provide custom schema locations if you need full CRD validation.

Exit codes

• 0 – all checks passed
• 1 – at least one failure (parse/lint/schema)
• 2 – a required tool is missing

---

CI / pre-commit examples (optional)

pre-commit (format + lint before committing):

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: yamlfmt
        name: yamlfmt
        entry: bash -c 'yamlfmt -lint "$@"'
        language: system
        files: \.(yml|yaml)$
      - id: yamllint
        name: yamllint
        entry: yamllint
        language: system
        files: \.(yml|yaml)$

GitHub Actions (lint all YAML):

# .github/workflows/yaml-lint.yml
name: yaml-lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: sudo apt-get update && sudo apt-get install -y yamllint
      - run: yamllint .

---

For Kubernetes validation in CI, add a step that runs kubeconform on the directories holding manifests.

Script

• Make script executable:

  chmod +x check-yaml-v11.sh

• Execute script in report only mode (defaults to ~/Projects directory):

  ./check-yaml-v11.sh

• Execute script in interactive mode:

  ./check-yaml-v11.sh -i

• Execute script in interactive mode against a specific directory:

  ./check-yaml-v11.sh ~/Projects/cloudflare -i