github-actions-troubleshooter

name	github-actions-troubleshooter
description	Diagnose and fix GitHub Actions workflow failures, CI/CD pipeline issues, YAML syntax errors, and workflow configuration problems. Use when debugging failed CI runs, fixing workflow errors, or optimizing GitHub Actions. Keywords: github actions, CI, workflow, pipeline, yml, yaml, actions failure, CI failure, workflow error

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: Deno
• Pre-commit checks: deno task pre-commit (format + typecheck + test)
• 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: denoland/setup-deno@v2
        with:
          deno-version: v2.x
          cache: true
      - run: deno install --frozen
      - run: deno task build
      - run: deno task typecheck
      - run: deno task test

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: deno task --eval "prettier --config .config/.prettierrc --check ."

✅ Verification

• Run locally: deno task fmt
• Commit formatted files
• Monitor next CI run

7. Prevention & Best Practices

Pre-commit hooks:

• Run formatters before commit
• Validate locally before pushing
• Use deno task 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"