• Validating workflow files: Checking

  .github/workflows/*.yml

  for syntax errors and best practices
• Testing workflows locally: Running workflows with

  act

  before pushing to GitHub
• Debugging workflow failures: Identifying issues in workflow configuration
• Validating custom actions: Checking composite, Docker, or JavaScript actions
• Verifying public actions: Validating usage of actions from GitHub Marketplace
• Pre-commit validation: Ensuring workflows are valid before committing

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

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)

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

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

  references/

runs-on: ubuntu-lastest

label "ubuntu-lastest" is unknown

references/runners.md

references/common_errors.md

Error:

label "ubuntu-lastest" is unknown

Cause: Typo in runner label (from

references/common_errors.md

):

yaml

# Bad
runs-on: ubuntu-lastest  # Typo

Fix (from

references/common_errors.md

):

yaml

# Good
runs-on: ubuntu-latest

Valid runner labels (from

references/runners.md

):

• ubuntu-latest

  ,

  ubuntu-24.04

  ,

  ubuntu-22.04

• windows-latest

  ,

  windows-2025

  ,

  windows-2022

• macos-latest

  ,

  macos-15

  ,

  macos-14

runs-on: ubuntu-latest

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

"[action-name] [version] github action documentation"

1. Always validate locally first - Catch errors before pushing
2. Use actionlint in CI/CD - Automate validation in pipelines
3. Pin action versions - Use

   @v6

   not

   @main

   for stability; SHA pinning for security
4. Keep tools updated - Regularly update actionlint and act
5. Use web search for unknown actions - Verify usage with documentation
6. Check version compatibility - See

   references/action_versions.md

7. Enable shellcheck - Catch shell script issues early
8. Review security warnings - Address script injection issues

• 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

  examples/

  ) can only be validated with actionlint

references/common_errors.md

Cause: Day of week 8 doesn't exist (valid: 0-6, where 0 = Sunday)

yaml

# Bad
schedule:
  - cron: '0 0 * * 8'  # Day 8 doesn't exist

# Good
schedule:
  - cron: '0 0 * * 0'  # Sunday

CRON format:

minute hour day month weekday

• Weekday: 0-6 (0 = Sunday)

8

0

1-6

references/common_errors.md

references/runners.md

Cause: Typo in runner label

yaml

# Bad
runs-on: ubuntu-lastest  # Typo

# Good
runs-on: ubuntu-latest

Valid labels (from

references/runners.md

):

• ubuntu-latest

  (Ubuntu 24.04)

• ubuntu-24.04

  ,

  ubuntu-22.04

• macos-latest

  (macOS 15)

• windows-latest

  (Windows Server 2022)

ubuntu-lastest

ubuntu-latest

references/action_versions.md

Action	Current Version	Minimum Supported
actions/checkout	v6	v4

SHA Pinning Best Practice:

yaml

# Recommended: SHA pinning with version comment
- uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0

@v3

@v6

references/common_errors.md

Warning: Potential script injection via untrusted input

yaml

# Bad - vulnerable to injection
run: echo ${{ github.event.issue.title }}

# Good - use environment variables
env:
  TITLE: ${{ github.event.issue.title }}
run: echo "$TITLE"

Why: Untrusted input (issue titles, PR bodies, commit messages) can contain malicious commands. Using environment variables sanitizes the input.

references/common_errors.md

Error: Job 'deploy' depends on job 'biuld' which does not exist

yaml

# Bad
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: biuld  # Typo

# Good
jobs:
  build:
    runs-on: ubuntu-latest
  deploy:
    needs: build

biuld

build

0 0 * * 8

0 0 * * 0

ubuntu-lastest

ubuntu-latest

checkout@v3

@v6.0.0

${{ }}

needs: biuld

needs: build

• 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

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/