🐞 Bug Summary

The check-yaml pre-commit hook fails when running make pre-commit, blocking commits due to legitimate Kubernetes manifest files that contain multiple YAML documents separated by --- delimiters. This is a standard Kubernetes pattern for defining multiple resources in a single file.

🧩 Affected Component

Select the area of the project impacted:

• mcpgateway - API
• mcpgateway - UI (admin panel)
• mcpgateway.wrapper - stdio wrapper
• Federation or Transports
• CLI, Makefiles, or shell scripts
• Container setup (Docker/Podman/Compose)
• Other (explain below)

🔁 Steps to Reproduce

1. Run make pre-commit in the project root
2. Observe the check-yaml hook failure
3. Note the error complains about "another document" in the YAML stream

🤔 Expected Behavior

The check-yaml hook should allow multi-document YAML files, which are standard for Kubernetes manifests and other YAML-based configuration systems. Files with multiple documents separated by --- are valid YAML and should pass validation.

📓 Logs / Error Output

✅ Check YAML............................................................Failed
- hook id: check-yaml
- exit code: 1

while scanning a plain scalar
  in "tests/performance/plugins/config.yaml", line 520, column 31
found unexpected ':'
  in "tests/performance/plugins/config.yaml", line 520, column 35
expected a single document in the stream
  in "examples/deployment-configs/cert-manager-issuer-example.yaml", line 20, column 1
but found another document
  in "examples/deployment-configs/cert-manager-issuer-example.yaml", line 28, column 1

🧠 Environment Info

You can retrieve most of this from the /version endpoint.

🧩 Additional Context (optional)

Affected File:

• examples/deployment-configs/cert-manager-issuer-example.yaml - Kubernetes cert-manager configuration with 3 resources (Issuer, Certificate, Issuer)

File Structure:
The file contains three Kubernetes resources separated by ---:

1. Self-signed Issuer (lines 20-26)
2. CA Certificate (lines 28-46)
3. CA Issuer (lines 48-58)

This is the standard Kubernetes pattern for multi-resource manifests.

Potential Solutions:

1. Add --allow-multiple-documents argument to the check-yaml hook in .pre-commit-config.yaml
2. Exclude examples/deployment-configs/ from the check-yaml hook
3. Split the multi-document YAML into separate files (not recommended - breaks Kubernetes conventions)

Configuration Location:
The hook is configured in .pre-commit-config.yaml at lines 289-293:

- id: check-yaml
  name: ✅ Check YAML
  description: Checks YAML files for parseable syntax.
  types: [yaml]
  exclude: ^(docs/|charts/)

Recommended Fix:
Add the --allow-multiple-documents argument:

- id: check-yaml
  name: ✅ Check YAML
  description: Checks YAML files for parseable syntax.
  types: [yaml]
  exclude: ^(docs/|charts/)
  args: ['--allow-multiple-documents']