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 integrating tools like actionlint and yamllint, it helps developers catch errors early, optimize CI/CD pipelines, and maintain secure, efficient automation scripts, ultimately reducing failed builds and 'trial-and-error' commits.
Use Cases
- Pre-commit Validation: Automatically check .github/workflows/*.yml files for syntax errors and linting issues before committing changes to the repository.
- Troubleshooting CI Failures: Quickly diagnose and fix common GitHub Actions errors such as invalid contexts, missing required fields, or incorrect action versions when a workflow fails.
- Security & Best Practice Auditing: Review existing workflows to ensure they follow security guidelines, such as using specific action versions instead of @main and configuring minimal necessary permissions.
- Workflow Scaffolding: Assist in the creation of new, robust CI/CD pipelines by providing checklists and validation methods for initial setup and configuration.
| 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