Github Actions Workflow Validator

{
  "hookConfig": {
    "hooks": {
      "postToolUse": {
        "script": "./.claude/hooks/github-actions-workflow-validator.sh",
        "matchers": [
          "write",
          "edit"
        ]
      }
    }
  },
  "scriptContent": "#!/usr/bin/env bash\n\n# Read the tool input from stdin\nINPUT=$(cat)\nTOOL_NAME=$(echo \"$INPUT\" | jq -r '.tool_name')\nFILE_PATH=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // .tool_input.path // \"\"')\n\nif [ -z \"$FILE_PATH\" ]; then\n  exit 0\nfi\n\n# Check if this is a GitHub Actions workflow file\nif [[ \"$FILE_PATH\" == *.github/workflows/*.yml ]] || [[ \"$FILE_PATH\" == *.github/workflows/*.yaml ]]; then\n  echo \"🔄 Validating GitHub Actions workflow: $(basename \"$FILE_PATH\")\" >&2\n  \n  # Initialize validation counters\n  WARNINGS=0\n  ERRORS=0\n  SUGGESTIONS=0\n  \n  # Function to report issues\n  report_issue() {\n    local level=\"$1\"\n    local message=\"$2\"\n    \n    case \"$level\" in\n      \"ERROR\")\n        echo \"❌ ERROR: $message\" >&2\n        ERRORS=$((ERRORS + 1))\n        ;;\n      \"WARNING\")\n        echo \"⚠️ WARNING: $message\" >&2\n        WARNINGS=$((WARNINGS + 1))\n        ;;\n      \"SUGGESTION\")\n        echo \"💡 SUGGESTION: $message\" >&2\n        SUGGESTIONS=$((SUGGESTIONS + 1))\n        ;;\n      \"INFO\")\n        echo \"ℹ️ INFO: $message\" >&2\n        ;;\n    esac\n  }\n  \n  # Check if file exists and is readable\n  if [ ! -f \"$FILE_PATH\" ]; then\n    report_issue \"ERROR\" \"Workflow file not found: $FILE_PATH\"\n    exit 1\n  fi\n  \n  # 1. YAML Syntax Validation\n  echo \"📋 Checking YAML syntax...\" >&2\n  \n  # Try actionlint first (most comprehensive)\n  if command -v actionlint &> /dev/null; then\n    echo \"   Using actionlint for comprehensive validation...\" >&2\n    \n    ACTIONLINT_OUTPUT=$(actionlint \"$FILE_PATH\" 2>&1)\n    ACTIONLINT_EXIT_CODE=$?\n    \n    if [ $ACTIONLINT_EXIT_CODE -eq 0 ]; then\n      echo \"   ✅ actionlint validation passed\" >&2\n    else\n      report_issue \"ERROR\" \"actionlint validation failed\"\n      echo \"$ACTIONLINT_OUTPUT\" >&2\n    fi\n  else\n    # Fallback to yamllint\n    if command -v yamllint &> /dev/null; then\n      echo \"   Using yamllint for YAML validation...\" >&2\n      if yamllint \"$FILE_PATH\" 2>/dev/null; then\n        echo \"   ✅ YAML syntax valid (yamllint)\" >&2\n      else\n        report_issue \"WARNING\" \"yamllint found issues in YAML syntax\"\n      fi\n    # Fallback to Python YAML parser\n    elif command -v python3 &> /dev/null; then\n      echo \"   Using Python YAML parser for validation...\" >&2\n      if python3 -c \"import yaml; yaml.safe_load(open('$FILE_PATH'))\" 2>/dev/null; then\n        echo \"   ✅ YAML syntax valid (Python)\" >&2\n      else\n        report_issue \"ERROR\" \"Invalid YAML syntax detected\"\n      fi\n    else\n      report_issue \"WARNING\" \"No YAML validator available (actionlint, yamllint, or python3)\"\n    fi\n  fi\n  \n  # 2. Action Version Validation\n  echo \"🔍 Checking action versions...\" >&2\n  \n  # Check for outdated action versions\n  OUTDATED_ACTIONS=(\n    \"actions/checkout@v[12]\"\n    \"actions/setup-node@v[12]\"\n    \"actions/setup-python@v[12]\"\n    \"actions/cache@v[12]\"\n    \"actions/upload-artifact@v[12]\"\n    \"actions/download-artifact@v[12]\"\n  )\n  \n  for pattern in \"${OUTDATED_ACTIONS[@]}\"; do\n    if grep -q \"$pattern\" \"$FILE_PATH\" 2>/dev/null; then\n      ACTION_NAME=$(echo \"$pattern\" | cut -d'@' -f1)\n      report_issue \"WARNING\" \"Using outdated $ACTION_NAME version - consider upgrading to latest\"\n    fi\n  done\n  \n  # Check for unpinned action versions (security risk)\n  if grep -E 'uses:.*@(main|master|develop)' \"$FILE_PATH\" >&2 2>/dev/null; then\n    report_issue \"WARNING\" \"Actions using branch references instead of pinned versions detected\"\n    echo \"   💡 Use specific version tags or commit SHAs for security\" >&2\n  fi\n  \n  # 3. Security Best Practices\n  echo \"🔒 Checking security best practices...\" >&2\n  \n  # Check for explicit permissions\n  if ! grep -q \"permissions:\" \"$FILE_PATH\" 2>/dev/null; then\n    report_issue \"SUGGESTION\" \"Consider adding explicit 'permissions:' for better security\"\n    echo \"   Example: permissions: { contents: read, actions: read }\" >&2\n  fi\n  \n  # Check for pull_request_target usage (potential security risk)\n  if grep -q \"pull_request_target:\" \"$FILE_PATH\" 2>/dev/null; then\n    report_issue \"WARNING\" \"pull_request_target can be a security risk - ensure proper handling\"\n  fi\n  \n  # Check for secrets in plain text (basic check)\n  if grep -iE '(password|secret|token|key).*:.*[a-zA-Z0-9]+' \"$FILE_PATH\" | grep -v '\\${{' >&2 2>/dev/null; then\n    report_issue \"ERROR\" \"Potential hardcoded secrets detected - use GitHub secrets instead\"\n  fi\n  \n  # 4. Performance and Best Practices\n  echo \"⚡ Checking performance best practices...\" >&2\n  \n  # Check for caching\n  if ! grep -q \"cache\" \"$FILE_PATH\" 2>/dev/null && (grep -q \"npm install\" \"$FILE_PATH\" || grep -q \"pip install\" \"$FILE_PATH\" || grep -q \"bundle install\" \"$FILE_PATH\") 2>/dev/null; then\n    report_issue \"SUGGESTION\" \"Consider adding caching for dependencies to improve workflow speed\"\n  fi\n  \n  # Check for matrix strategy usage\n  if ! grep -q \"strategy:\" \"$FILE_PATH\" 2>/dev/null && grep -q \"runs-on:\" \"$FILE_PATH\" 2>/dev/null; then\n    report_issue \"SUGGESTION\" \"Consider using matrix strategy for testing multiple versions/platforms\"\n  fi\n  \n  # Check for conditional job execution\n  if ! grep -q \"if:\" \"$FILE_PATH\" 2>/dev/null; then\n    report_issue \"SUGGESTION\" \"Consider using conditional execution to optimize workflow runs\"\n  fi\n  \n  # 5. Workflow Structure Validation\n  echo \"📋 Checking workflow structure...\" >&2\n  \n  # Check for required fields\n  if ! grep -q \"name:\" \"$FILE_PATH\" 2>/dev/null; then\n    report_issue \"WARNING\" \"Workflow should have a descriptive 'name' field\"\n  fi\n  \n  if ! grep -q \"on:\" \"$FILE_PATH\" 2>/dev/null; then\n    report_issue \"ERROR\" \"Workflow must have 'on:' trigger definition\"\n  fi\n  \n  if ! grep -q \"jobs:\" \"$FILE_PATH\" 2>/dev/null; then\n    report_issue \"ERROR\" \"Workflow must have 'jobs:' section\"\n  fi\n  \n  # Check for environment variables\n  if grep -q \"env:\" \"$FILE_PATH\" 2>/dev/null; then\n    echo \"   ✅ Environment variables defined\" >&2\n  fi\n  \n  # 6. Action-Specific Checks\n  echo \"🎯 Checking action-specific patterns...\" >&2\n  \n  # Check for Node.js setup\n  if grep -q \"actions/setup-node\" \"$FILE_PATH\" 2>/dev/null; then\n    if ! grep -q \"node-version\" \"$FILE_PATH\" 2>/dev/null; then\n      report_issue \"WARNING\" \"setup-node should specify node-version\"\n    fi\n    \n    if ! grep -q \"cache:\" \"$FILE_PATH\" 2>/dev/null; then\n      report_issue \"SUGGESTION\" \"Consider enabling cache for setup-node (e.g., cache: npm)\"\n    fi\n  fi\n  \n  # Check for Python setup\n  if grep -q \"actions/setup-python\" \"$FILE_PATH\" 2>/dev/null; then\n    if ! grep -q \"python-version\" \"$FILE_PATH\" 2>/dev/null; then\n      report_issue \"WARNING\" \"setup-python should specify python-version\"\n    fi\n  fi\n  \n  # Check for checkout action\n  if grep -q \"actions/checkout\" \"$FILE_PATH\" 2>/dev/null; then\n    # Check if fetch-depth is appropriate for the use case\n    if grep -q \"fetch-depth: 0\" \"$FILE_PATH\" 2>/dev/null; then\n      report_issue \"INFO\" \"Using full history checkout - ensure this is necessary\"\n    fi\n  fi\n  \n  # 7. Generate Summary Report\n  echo \"\" >&2\n  echo \"📊 GitHub Actions Validation Summary:\" >&2\n  echo \"=====================================\" >&2\n  echo \"   📄 Workflow: $(basename \"$FILE_PATH\")\" >&2\n  echo \"   ❌ Errors: $ERRORS\" >&2\n  echo \"   ⚠️ Warnings: $WARNINGS\" >&2\n  echo \"   💡 Suggestions: $SUGGESTIONS\" >&2\n  \n  if [ \"$ERRORS\" -eq 0 ] && [ \"$WARNINGS\" -eq 0 ]; then\n    echo \"   ✅ Validation Status: PASSED\" >&2\n  elif [ \"$ERRORS\" -eq 0 ]; then\n    echo \"   ✅ Validation Status: PASSED (with warnings)\" >&2\n  else\n    echo \"   ❌ Validation Status: FAILED\" >&2\n  fi\n  \n  echo \"\" >&2\n  echo \"💡 GitHub Actions Best Practices:\" >&2\n  echo \"   • Pin actions to specific versions or commit SHAs\" >&2\n  echo \"   • Use explicit permissions for security\" >&2\n  echo \"   • Cache dependencies to improve performance\" >&2\n  echo \"   • Use matrix strategies for cross-platform testing\" >&2\n  echo \"   • Add conditional execution to optimize runs\" >&2\n  echo \"   • Keep secrets out of workflow files\" >&2\n  \n  # Exit with error if there are critical issues\n  if [ \"$ERRORS\" -gt 0 ]; then\n    echo \"⚠️ Workflow has critical errors that should be fixed\" >&2\n    exit 1\n  fi\n  \nelse\n  # Not a GitHub Actions workflow file\n  exit 0\nfi\n\nexit 0"
}