GitHub Actions Troubleshooter

Diagnoses and fixes GitHub Actions workflow failures and configuration issues.

Instructions

When activated, follow this systematic troubleshooting approach:

1. Identify the Failure

Get workflow status:

gh run list --limit 5                    # Recent runs
gh run view <run-id>                     # Specific run details
gh run view <run-id> --log-failed        # Failed job logs only

Analyze the failure:

• Parse error messages from logs
• Identify which job/step failed
• Note the exit code and error type
• Check if it's intermittent or consistent

2. Common Failure Categories

YAML Syntax Errors

• Invalid indentation (must use spaces, not tabs)
• Missing required fields (

  name

  ,

  on

  ,

  jobs

  )
• Invalid step format
• Quote escaping issues

Fix approach:

• Read the workflow file with Read tool
• Validate YAML structure
• Check GitHub Actions syntax documentation
• Use Edit tool to fix syntax

Dependency/Setup Issues

• Node/Python/etc version mismatches
• Missing dependencies in package.json/requirements.txt
• Cache invalidation needed
• Setup action version incompatibility

Fix approach:

# Pin versions explicitly
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'

Test/Build Failures

• Tests failing in CI but passing locally
• Environment variable differences
• File path issues (case sensitivity on Linux)
• Missing environment secrets

Fix approach:

• Compare local vs CI environment
• Check for hardcoded paths
• Verify secrets are configured
• Add debugging output

Permission Errors

• GITHUB_TOKEN

  insufficient permissions
• File permission issues
• Branch protection violations

Fix approach:

permissions:
  contents: write
  pull-requests: write
  checks: read

Timeout/Performance Issues

• Jobs exceeding 6-hour limit
• Slow dependency installation
• Missing caching
• Inefficient matrix strategies

Fix approach:

• Add caching for dependencies
• Parallelize independent jobs
• Optimize test suites
• Use workflow artifacts efficiently

3. Diagnostic Workflow

Step 1: Read the workflow file

# Find workflow files
fd -e yml -e yaml . .github/workflows

Step 2: Get recent run logs

# View latest failed run
gh run view --log-failed

# Or specific run by ID
gh run view 1234567890 --log

Step 3: Identify root cause

• Parse error messages
• Check for known patterns
• Review recent changes with git log
• Compare with working runs

Step 4: Apply fix

• Use Edit tool for workflow changes
• Test locally if possible
• Create PR for review
• Monitor next run

4. Common Fixes

Format Check Failures (Prettier/ESLint)

# Before commit, run formatters
- name: Format code
  run: pnpm exec prettier --write .

# Or enforce in CI
- name: Check formatting
  run: pnpm exec prettier --check .

Missing Environment Variables

env:
  NODE_ENV: production
  API_URL: ${{ secrets.API_URL }}

jobs:
  build:
    env:
      CUSTOM_VAR: value

Caching Dependencies

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'  # or 'npm', 'yarn'

# Or manual cache
- uses: actions/cache@v4
  with:
    path: ~/.cache
    key: ${{ runner.os }}-cache-${{ hashFiles('**/pnpm-lock.yaml') }}

Matrix Strategy for Multiple Versions

strategy:
  matrix:
    node-version: [18, 20, 22]
    os: [ubuntu-latest, windows-latest]
jobs:
  test:
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

5. Project-Specific Context

This project uses:

• Package Manager: pnpm
• Pre-commit checks:

  pnpm run pre-commit

  (format + lint + typecheck)
• Common CI tasks: format check, typecheck, build, test

Standard workflow pattern:

name: CI
on: [push, pull_request]
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm run pre-commit
      - run: pnpm run test
      - run: pnpm run build

6. Output Format

Present findings as:

🔍 Diagnosis

• Job:

  format-check

• Step:

  Run prettier --check

• Error:

  Code style issues found in 11 files

• Root Cause: Files not formatted with Prettier

🔧 Fix Applied

# File: .github/workflows/ci.yml:15
- name: Format check
  run: pnpm exec prettier --config .config/.prettierrc --check .

✅ Verification

• Run locally:

  pnpm exec prettier --write .

• Commit formatted files
• Monitor next CI run

7. Prevention & Best Practices

Pre-commit hooks:

• Run formatters before commit
• Validate locally before pushing
• Use

  pnpm run pre-commit

Workflow best practices:

• Pin action versions (

  actions/checkout@v4

  not

  @main

  )
• Use caching for dependencies
• Set explicit timeouts
• Add descriptive step names
• Use

  if: failure()

  for debugging steps

Security:

• Minimize

  GITHUB_TOKEN

  permissions
• Don't log secrets
• Use

  secrets

  context, not env vars for sensitive data
• Review third-party actions before use

Tools to Use

• Read: View workflow YAML files
• Edit: Fix workflow configuration
• Bash(gh:*): Get run logs, workflow status
• Bash(git:*): Check recent changes, blame
• Grep: Search for patterns in logs/workflows
• WebFetch: Check GitHub Actions documentation

Example Activation

These user requests will trigger this skill:

• "Why is my GitHub Actions workflow failing?"
• "Fix the CI pipeline error"
• "The format check is failing in CI"
• "Help debug this workflow YAML"
• "My tests pass locally but fail in GitHub Actions"