validate-workflow

Validate GitHub Actions workflow files for syntax, best practices, and correctness. Use before committing workflow changes or when workflows fail.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

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.
namevalidate-workflow
descriptionValidate GitHub Actions workflow files for syntax, best practices, and correctness. Use before committing workflow changes or when workflows fail.
mcp_fallbacknone
categoryci
user-invocablefalse

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
  • 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

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 definitions
  • actionlint config - Action linting rules

References