---

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

Copy# 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

Copy# 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

Copypip install actionlint
actionlint .github/workflows/*.yml

3. yamllint

Copyyamllint .github/workflows/*.yml

Common Issues

Workflow Checklist

• Valid YAML syntax
• on trigger configured correctly
• All jobs have runs-on
• All steps have run or uses
• Action versions are specific (not @main)
• All secrets/vars available
• Timeouts set appropriately
• Permissions configured correctly

Best Practices

Copyname: 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

Copy# 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

Configuration Files

• .pre-commit-config.yaml - Pre-commit hooks
• .github/workflows/ - Workflow definitions
• actionlint config - 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-failures for debugging failures