validate-actions 1.0.4

CLI for github actions workflow validation

validate-actions

GitHub Actions workflow validation and linting from the CLI.

Catch configuration errors, typos, and best practice violations in your GitHub Actions workflows before you push to production.

---

🚀 Quick Start

Installation

# Install from PyPI
pip install validate-actions

Basic Usage

# Validate all workflows in your repository
validate-actions

# Validate a specific workflow file
validate-actions .github/workflows/ci.yml

# Auto-fix issues where possible
validate-actions --fix

# More options
validate-actions --help

---

How it works

---

🔧 Configuration

Extending Rules

validate-actions supports custom. You can extend the tool with your own rules without modifying the core codebase.

See validate_actions/rules/rules.yml for configuration format and examples of creating custom rules.

---

🏃‍♂️ Integration Examples

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: validate-actions
        name: Validate GitHub Actions
        entry: validate-actions
        language: system
        files: ^\.github/workflows/.*\.ya?ml$

Note: Requires validate-actions to be installed globally or available in your PATH. For poetry projects, consider using entry: poetry run validate-actions.

VS Code Task

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Validate Actions",
      "type": "shell", 
      "command": "validate-actions",
      "group": "build",
      "presentation": {
        "echo": true,
        "reveal": "always"
      }
    }
  ]
}

Note: Assumes global installation (pip install validate-actions). For other setups, replace command with:

• Poetry: "poetry run validate-actions"
• Pipx: "pipx run validate-actions"
• ...

GitHub Actions Workflow

# .github/workflows/validate.yml
name: Validate Workflows
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      - run: pip install validate-actions
      - name: Validate with warning limit
        run: validate-actions
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note: Use --max-warnings N to set warning limits, or --quiet to suppress warning output entirely.

---

🚦 Exit Codes

• 0: Success (no errors, warnings under limit)
• 1: Errors found OR warnings exceed --max-warnings limit

By default, warnings don't cause exit code 1 (non-blocking):

validate-actions              # Exit 0 even with warnings
validate-actions --quiet      # Exit 0, suppress warning output  

Use --max-warnings to fail builds when warnings exceed a threshold:

validate-actions --max-warnings 0    # Exit 1 on any warnings (strict)
validate-actions --max-warnings 5    # Exit 1 if more than 5 warnings

Perfect for CI/CD integration:

# .github/workflows/validate.yml
- name: Validate Workflows (Allow Warnings)
  run: validate-actions
  # Will only fail on errors, not warnings

---

📖 Documentation

Full API documentation is available at: https://konradhorber.github.io/validate-actions/

🛠️ Development

See DEV_README.md for detailed development setup, architecture overview, and contribution guidelines.

---

🤝 Contributing

We welcome contributions! Please see DEV_README.md for development setup and guidelines.

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

Built with:

• PyYAML for robust YAML parsing
• Typer for the CLI interface
• Rich for beautiful terminal output
• python-dotenv for environment variable management
• sphinx for docs generation

Inspired by tools like ESLint and the GitHub Actions community's need for better workflow validation.