Add YAML workflow validation tools and process

[toshi0806]

Problem Description

GitHub Actions workflows written in YAML can have syntax errors that only become apparent after pushing to the repository. This can lead to failed workflows and wasted time debugging issues that could have been caught locally.

Recommended Tools

1. yamllint - A linter for YAML files

   • Checks for syntax validity
   • Enforces consistent formatting
   • Detects common mistakes

2. actionlint - Static checker for GitHub Actions workflow files

   • Validates workflow syntax
   • Checks for common mistakes in GitHub Actions
   • Type checks expressions
   • Validates job dependencies

Implementation Steps

1. Install validation tools:

   # macOS
   brew install yamllint actionlint
   
   # Ubuntu/Debian
   sudo apt-get install yamllint
   # actionlint needs to be installed from releases

2. Create configuration files:

   • .yamllint.yml for yamllint configuration
   • Configure rules for consistent formatting

3. Add pre-commit hooks:

   • Use pre-commit framework to run checks automatically
   • Prevent commits with invalid YAML

4. Add validation to CI/CD:

   • Include validation step in GitHub Actions
   • Ensure all PRs pass YAML validation

5. Document the process:

   • Update README with validation instructions
   • Add troubleshooting guide

Benefits

• Early error detection: Catch syntax errors before pushing
• Consistent formatting: Maintain readable workflow files
• Reduced debugging time: Avoid runtime failures due to syntax issues
• Better collaboration: Ensure all contributors follow the same standards
• Improved reliability: Reduce workflow failures due to configuration errors

Example Configuration

.yamllint.yml:

extends: default
rules:
  line-length:
    max: 120
    level: warning
  truthy:
    allowed-values: ['true', 'false', 'on', 'off']

Pre-commit hook (.pre-commit-config.yaml):

repos:
  - repo: https://github.com/adrienverge/yamllint
    rev: v1.35.1
    hooks:
      - id: yamllint
        args: [-c=.yamllint.yml]
  - repo: https://github.com/rhysd/actionlint
    rev: v1.6.26
    hooks:
      - id: actionlint

Reference Implementation

The latex-template repository has already implemented this validation process and can serve as a reference.