Ghanon

Ghanon(dorf) - A strict GitHub Actions workflow linter that validates your workflows against best practices.

🎯 What is Ghanon?

Ghanon is a powerful linter for GitHub Actions workflows that goes beyond basic YAML validation. It validates your .github/workflows/*.yml files against the official GitHub Actions schema using Pydantic models and enforces best practices with custom validation rules.

Key Features

• 📋 Complete Schema Validation: Validates against the full GitHub Actions Workflow Schema
• 🎯 Precise Error Reporting: Shows exact line numbers where validation errors occur
• ✨ Best Practices Enforcement: Custom validators that catch common anti-patterns and security issues
• 🔒 Security-First: Enforces principle of least privilege for secrets and permissions
• 🚀 CI/CD Ready: Easy to integrate into your continuous integration pipelines
• 💯 Type-Safe: Built with Pydantic for robust validation

Best Practices Enforced

• ❌ Discourages secrets: inherit (principle of least privilege)
• 🔍 Validates job IDs, step configurations, and runner specifications
• 🛡️ Checks permissions, concurrency settings, and environment configurations

📦 Installation

Ghanon requires Python 3.14 or higher.

Using pip

pip install ghanon

Using pipx (recommended for CLI tools)

pipx install ghanon

Using uv

uv tool install ghanon

🚀 Usage

Command Line

Validate a single workflow file:

ghanon path/to/workflow.yml

Validate all workflows in your repository:

ghanon .github/workflows/*.yml

In CI/CD Pipelines

Add Ghanon to your GitHub Actions workflow:

name: Validate Workflows

on:
  pull_request:
    paths:
      - '.github/workflows/**'
  push:
    branches:
      - main

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'
      
      - name: Install Ghanon
        run: pip install ghanon
      
      - name: Validate workflows
        run: ghanon .github/workflows/*.yml

📖 Example Output

When Ghanon finds issues in your workflow:

❌ Validation failed for workflow.yml

Error at line 15 (jobs.build.secrets):
  Do not use `secrets: inherit`. Define secrets explicitly for principle of least privilege.

🛠️ Development

Prerequisites

• Python 3.14+
• Task (task runner)
• uv (package manager)

Setup

# Clone the repository
git clone https://github.com/nikoheikkila/ghanon.git
cd ghanon

# Install dependencies
task install

# Run the linter
uv tool install .
ghanon path/to/workflow.yml

Testing

Ghanon maintains 100% test coverage:

# Run full test suite (format, lint, test)
task test

# Run only unit tests
task test:unit

# Watch mode for TDD
task test:watch

Code Quality

# Lint code
task lint

# Format code
task format

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct before submitting pull requests.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following our conventions
4. Ensure all tests pass (task test)
5. Commit using Conventional Commits
6. Push to your fork and submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Pydantic for robust validation
• Schema based on SchemaStore's GitHub Workflow Schema
• Inspired by the need for better GitHub Actions workflow validation

📞 Support

If you encounter any issues or have questions:

• 🐛 Report a bug
• 💡 Request a feature
• 💬 Ask a question

Made with ❤️ by Niko Heikkilä