validate-workflow
Validate GitHub Actions workflow files for syntax, best practices, and correctness. Use before committing workflow changes or when workflows fail.
When & Why to Use This Skill
This Claude skill provides comprehensive validation for GitHub Actions workflow files, ensuring syntax accuracy, adherence to best practices, and overall correctness. By leveraging industry-standard tools like actionlint and yamllint, it helps developers identify structural errors, invalid action versions, and missing required fields before deployment, significantly reducing CI/CD pipeline failures and streamlining the DevOps lifecycle.
Use Cases
- Creating new GitHub Actions workflows: Ensure your initial CI/CD setup is error-free and follows security best practices from the start.
- Modifying existing CI/CD pipelines: Safely update workflow logic, triggers, or job configurations without breaking the build process.
- Debugging workflow syntax errors: Quickly identify and fix YAML formatting issues, invalid context expressions, or missing required fields like 'runs-on'.
- Pre-commit validation: Use as a quality gate to verify workflow integrity and permission configurations before pushing changes to a remote repository.
| name | validate-workflow |
|---|---|
| description | Validate GitHub Actions workflow files for syntax, best practices, and correctness. Use before committing workflow changes or when workflows fail. |
| mcp_fallback | none |
| category | ci |
| user-invocable | false |
CI Workflow Validation Skill
Validate GitHub Actions workflow files for correctness.
When to Use
- Creating new workflow
- Modifying existing workflow
- Workflow syntax errors
- Before committing workflow changes
Quick Reference
# List workflows
gh workflow list
# View workflow details
gh workflow view <workflow-name>
# Validate YAML
yamllint .github/workflows/*.yml
# Lint with actionlint
actionlint .github/workflows/*.yml
Validation Methods
1. GitHub CLI
# View workflow
gh workflow view deploy.yml
# List all workflows
gh workflow list
# Get workflow metadata
gh api repos/owner/repo/actions/workflows
2. actionlint
pip install actionlint
actionlint .github/workflows/*.yml
3. yamllint
yamllint .github/workflows/*.yml
Common Issues
| Issue | Example | Fix |
|---|---|---|
| Syntax error | on: [push pull_request] |
Add comma: on: [push, pull_request] |
| Invalid action version | uses: actions/checkout@v99 |
Use valid version: @v4 |
| Missing required field | Job missing runs-on |
Add runs-on: ubuntu-latest |
| Invalid context | ${{ job.status }} in wrong place |
Move to correct context |
Workflow Checklist
- Valid YAML syntax
-
ontrigger configured correctly - All jobs have
runs-on - All steps have
runoruses - Action versions are specific (not @main)
- All secrets/vars available
- Timeouts set appropriately
- Permissions configured correctly
Best Practices
name: Quality Check
on: [push, pull_request]
jobs:
quality:
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
steps:
- uses: actions/checkout@v4 # Specific version
- uses: actions/cache@v3
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip
- run: just pre-commit-all
Validation Workflow
# 1. Edit workflow
vim .github/workflows/test.yml
# 2. Validate YAML
yamllint .github/workflows/test.yml
# 3. Lint with actionlint
actionlint .github/workflows/test.yml
# 4. Review in GitHub
gh workflow view test.yml
# 5. Commit if valid
git add .github/workflows/test.yml
git commit -m "ci: update workflow"
Error Handling
| Error | Fix |
|---|---|
| "Invalid YAML" | Fix YAML syntax errors |
| "Unknown action" | Check action name and version |
| "Missing field" | Add required fields (run, uses, etc.) |
| "Invalid context" | Use correct context expression syntax |
Configuration Files
.pre-commit-config.yaml- Pre-commit hooks.github/workflows/- Workflow definitionsactionlintconfig - Action linting rules
References
- GitHub Actions docs: https://docs.github.com/en/actions
- Workflow syntax: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
- Related skill:
fix-ci-failuresfor debugging failures