pantheon-org/github-actions-validator

GitHub Actions Validator

Overview

Validate and test GitHub Actions workflows, custom actions, and public actions using industry-standard tools (actionlint and act). This skill provides comprehensive validation including syntax checking, static analysis, local workflow execution testing, and action verification with version-aware documentation lookup.

CRITICAL: Assistant Workflow (MUST FOLLOW)

Every validation MUST follow these steps. Skipping any step is non-compliant.

Step 1: Run Validation Script

cd .claude/skills/github-actions-validator
bash scripts/validate_workflow.sh <workflow-file-or-directory>

Step 2: For EACH Error - Consult Reference File

When actionlint or act reports ANY error, you MUST:

1. Read the appropriate reference file (see mapping below)
2. Find the matching error pattern
3. Extract the fix/solution

Step 3: Quote the Fix to User

For each error, provide:

1. Error message (from script output)
2. Explanation (from reference file)
3. Fix code (quoted from reference file)
4. Corrected code (applied to user's workflow)

Step 4: Verify Public Actions (if present)

For any public actions (uses: owner/action@version):

1. First check references/action_versions.md for known actions and versions
2. Use web search for unknown actions: "[action-name] [version] github action documentation"
3. Verify required inputs match
4. Check for deprecation warnings

Step 5: Provide Complete Summary

After all errors are addressed:

• List all fixes applied
• Note any warnings
• Recommend best practices from references/

Error-to-Reference Mapping

| Error Pattern / Output Category | Reference File | Section to Consult | |----------------------------------|---------------|--------------------| | runs-on:, runner, ubuntu, macos, windows | references/runners.md | Runner labels | | cron, schedule / [SCHEDULE] | references/common_errors.md | Schedule Errors | | ${{, expression, if: / [EXPRESSION] | references/common_errors.md | Expression Errors | | needs:, job, dependency / [SYNTAX] | references/common_errors.md | Job Configuration Errors | | uses:, action, input / [ACTION] | references/common_errors.md | Action Errors | | untrusted, injection, security / [SECURITY] | references/common_errors.md | Script Injection section | | syntax, yaml, unexpected | references/common_errors.md | Syntax Errors | | docker, container / [DOCKER] | references/act_usage.md | Troubleshooting | | [ACT-LIMIT], act fails but GitHub works | references/act_usage.md | Limitations | | @v3, @v4, deprecated, outdated | references/action_versions.md | Version table | | workflow_call, reusable, oidc | references/modern_features.md | Relevant section | | glob, path, paths:, pattern | references/common_errors.md | Path Filter Errors | | User asks about actionlint config | references/actionlint_usage.md | Provide examples | | Runner questions/errors | references/runners.md | Labels and availability |

Quick Start

Initial Setup

cd .claude/skills/github-actions-validator
bash scripts/install_tools.sh  # Installs act and actionlint to scripts/.tools/

Validation Commands

# Full validation (lint + test)
bash scripts/validate_workflow.sh .github/workflows/ci.yml

# Lint-only (fastest, no Docker required)
bash scripts/validate_workflow.sh --lint-only .github/workflows/ci.yml

# Test-only with act (requires Docker)
bash scripts/validate_workflow.sh --test-only .github/workflows/ci.yml

# Validate all workflows
bash scripts/validate_workflow.sh .github/workflows/

actionlint checks: YAML syntax, schema compliance, expression syntax, runner labels, action inputs/outputs, job dependencies, CRON syntax, glob patterns, shell scripts, security vulnerabilities.

Note: act has limitations — see references/act_usage.md.

Validating Resource Types

Workflows

# Single workflow
bash scripts/validate_workflow.sh .github/workflows/ci.yml

# All workflows
bash scripts/validate_workflow.sh .github/workflows/

Key validation points: triggers, job configurations, runner labels, environment variables, secrets, conditionals, matrix strategies.

Custom Local Actions

Create a test workflow that uses the custom action, then validate:

bash scripts/validate_workflow.sh .github/workflows/test-custom-action.yml

Public Actions

When workflows use public actions (e.g., actions/checkout@v6):

1. Use web search to find action documentation
2. Verify required inputs and version
3. Check for deprecation warnings
4. Run validation script

Search format: "[action-name] [version] github action documentation"

Reference Files Summary

| File | Content | |------|---------| | references/act_usage.md | Act tool usage, commands, options, limitations, troubleshooting | | references/actionlint_usage.md | Actionlint validation categories, configuration, integration | | references/common_errors.md | Common errors catalog with fixes | | references/action_versions.md | Current action versions, deprecation timeline, SHA pinning | | references/modern_features.md | Reusable workflows, SBOM, OIDC, environments, containers | | references/runners.md | GitHub-hosted runners (ARM64, GPU, M2 Pro, deprecations) |

Troubleshooting

| Issue | Solution | |-------|----------| | "Tools not found" | Run bash scripts/install_tools.sh | | "Docker daemon not running" | Start Docker or use --lint-only | | "Permission denied" | Run chmod +x scripts/*.sh | | act fails but GitHub works | See references/act_usage.md Limitations |

Debug Mode

actionlint -verbose .github/workflows/ci.yml  # Verbose actionlint
act -v                                         # Verbose act
act -n                                         # Dry-run (no execution)

Limitations

• act limitations: Not all GitHub Actions features work locally
• Docker requirement: act requires Docker to be running
• Network actions: Some GitHub API actions may fail locally
• Private actions: Cannot validate without access
• Runtime behavior: Static analysis cannot catch all issues
• File location: act can only validate workflows in .github/workflows/ directory; files outside (like assets/) can only be validated with actionlint

Quick Examples

Example 1: Pre-commit Validation

cd .claude/skills/github-actions-validator
bash scripts/validate_workflow.sh .github/workflows/
git add .github/workflows/ && git commit -m "Update workflows"

Example 2: Debug Failing Workflow

bash scripts/validate_workflow.sh --lint-only .github/workflows/failing.yml
# Fix issues
bash scripts/validate_workflow.sh .github/workflows/failing.yml

Complete Worked Example: Multi-Error Workflow

User's Problematic Workflow

name: Broken CI
on:
  schedule:
    - cron: '0 0 * * 8'  # ERROR 1
jobs:
  build:
    runs-on: ubuntu-lastest  # ERROR 2
    steps:
      - uses: actions/checkout@v3  # ERROR 3 (outdated)
      - run: echo ${{ github.event.issue.title }}  # ERROR 4 (security)
  deploy:
    needs: biuld  # ERROR 5 (typo)
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

Step 1: Run Validation

bash scripts/validate_workflow.sh --lint-only workflow.yml

Output:

[ERROR] invalid CRON format "0 0 * * 8"
[ERROR] label "ubuntu-lastest" is unknown
[WARN] "github.event.issue.title" is potentially untrusted
[ERROR] job "deploy" needs job "biuld" which does not exist

Step 2-3: Consult References and Quote Fixes to User

Using the Error-to-Reference Mapping table above, consult the relevant reference file for each error and quote the fix to the user:

| # | Error | Reference File | Fix | |---|-------|---------------|-----| | 1 | invalid CRON format "0 0 * * 8" | common_errors.md - Schedule Errors | Change 8 to 0 (weekday range is 0–6) | | 2 | label "ubuntu-lastest" is unknown | common_errors.md + runners.md | Change to ubuntu-latest | | 3 | checkout@v3 (outdated) | action_versions.md | Update to @v6 or SHA-pinned equivalent | | 4 | Untrusted input in run: | common_errors.md - Script Injection | Pass through environment variable | | 5 | needs: biuld (typo) | common_errors.md - Job Configuration | Change to needs: build |

Step 4: Corrected Workflow

name: Fixed CI
on:
  schedule:
    - cron: '0 0 * * 0'  # Fixed: Sunday (valid range 0-6)
jobs:
  build:
    runs-on: ubuntu-latest  # Fixed: typo corrected
    steps:
      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
      - name: Process issue
        env:
          TITLE: ${{ github.event.issue.title }}  # Fixed: sanitized via env var
        run: echo "$TITLE"
  deploy:
    needs: build  # Fixed: typo corrected
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying"

Step 5: Summary

| Error | Type | Fix Applied | |-------|------|-------------| | CRON 0 0 * * 8 | Schedule | Changed to 0 0 * * 0 | | ubuntu-lastest | Runner | Changed to ubuntu-latest | | checkout@v3 | Outdated Action | Updated to @v6.0.0 (SHA-pinned) | | Direct ${{ }} in run | Security | Wrapped in environment variable | | needs: biuld | Job Dependency | Changed to needs: build |

Recommendations:

• Run bash scripts/validate_workflow.sh --check-versions regularly
• Use SHA pinning for all actions in production workflows
• Always pass untrusted input through environment variables

Anti-Patterns

NEVER skip lint-only mode when Docker is unavailable

• WHY: Skipping validation entirely because Docker is not installed leaves syntax errors, schema violations, and security issues undetected. actionlint catches the majority of real errors without Docker.
• BAD: Skip all validation when Docker is not installed.
• GOOD: Run --lint-only mode which covers syntax, schema, and security checks without requiring a container runtime.

NEVER ignore script injection warnings from actionlint

• WHY: Script injection warnings flag real attack vectors. Untrusted github.event.* values interpolated directly into shell commands allow a pull request author to execute arbitrary code in your workflow.
• BAD: Dismiss SC2086 or script injection warnings as low priority and merge anyway.
• GOOD: Pass untrusted input through environment variables — env: PR_TITLE: ${{ github.event.pull_request.title }} — then reference "$PR_TITLE" in the run: step.

NEVER validate a workflow file in isolation when it uses workflow_call or matrix

• WHY: Reusable workflows and matrix strategies depend on caller-provided inputs and context that cannot be resolved by validating the file alone. Skipping caller validation misses entire classes of type and expression errors.
• BAD: Validate only the reusable workflow file without also validating the calling workflow.
• GOOD: Validate both the caller and callee; note any warnings that require runtime context that static analysis cannot resolve.

NEVER accept deprecation warnings as harmless

• WHY: Deprecated action major versions (e.g., @v2 when @v4 is current) may receive no security patches. A known vulnerability in a deprecated version is an open door into your CI environment.
• BAD: Leave actions/checkout@v2 in place after the validator warns it is outdated.
• GOOD: Update to the current SHA-pinned version from references/action_versions.md.

Summary

1. Setup: Install tools with install_tools.sh
2. Validate: Run validate_workflow.sh on workflow files
3. Fix: Address issues using reference documentation
4. Test: Verify locally with act (when possible)
5. Search: Use web search to verify unknown actions
6. Commit: Push validated workflows with confidence

References

| Topic | Reference | When to Use | | --- | --- | --- | | actionlint error patterns with explanations and fixes | Common Errors | Diagnosing a specific actionlint error message | | Runner labels, availability, and hardware specs | Runners | Choosing or validating a runs-on label | | Current version table for popular actions with SHA pins | Action Versions | Updating a deprecated or unpinned action reference | | Local workflow testing with act, limitations and workarounds | act Usage | Running workflows locally before pushing | | actionlint configuration and custom rule examples | actionlint Usage | Configuring actionlint or adding custom ignore rules | | Modern GHA features: job summaries, environments, containers | Modern Features | Validating workflows that use newer GitHub Actions APIs |