laurigates/github-actions-inspection

GitHub Actions Inspection

When to Use This Skill

| Use this skill when... | Use the linked sibling instead when... | |---|---| | Pulling status, logs, and conclusions from gh run for a failing workflow | Authoring or modifying a workflow YAML file — see claude-code-github-workflows | | Diagnosing flaky tests, timeouts, or auth-permission errors in a CI run | Searching upstream OSS issues for a library bug — see github-issue-search | | Rerunning failed jobs, watching in-progress runs, or extracting error lines | Building a workflow that auto-fixes CI failures — see github-workflow-auto-fix |

Expert knowledge for inspecting, debugging, and troubleshooting GitHub Actions workflow runs using gh CLI and GitHub API.

For detailed examples, advanced patterns, and best practices, see REFERENCE.md.

Core Expertise

Workflow Run Inspection

• Check workflow run status and conclusions
• List recent workflow runs with filtering
• View detailed run information
• Monitor in-progress workflows

Log Analysis

• Fetch workflow run logs
• Identify failing steps and jobs
• Extract error messages and stack traces
• Parse test failure output

Debugging Workflows

• Diagnose common failure patterns
• Correlate errors with code changes
• Identify flaky tests and race conditions
• Analyze timing and performance issues

Essential Commands

List Workflow Runs

# List all workflow runs
gh run list

# List runs for specific workflow
gh run list --workflow=ci.yml

# Filter by status
gh run list --status=failure
gh run list --status=in_progress

# Filter by branch
gh run list --branch=main

# Combine filters
gh run list --workflow=ci.yml --status=failure --limit 5

# JSON output for parsing
gh run list --json databaseId,status,conclusion,name,createdAt,headBranch

View Workflow Run Details

# View specific run
gh run view <run-id>

# View failed logs only
gh run view <run-id> --log-failed

# View specific job
gh run view <run-id> --job=<job-id>

# JSON output
gh run view <run-id> --json status,conclusion,jobs,startedAt,updatedAt

Download and Analyze Logs

# Download logs for run
gh run download <run-id>

# View failed step logs only
gh run view <run-id> --log-failed

# Extract specific job logs
gh api repos/:owner/:repo/actions/runs/<run-id>/logs | less

Watch Running Workflows

# Watch workflow progress
gh run watch <run-id>

# Watch with exit status
gh run watch <run-id> --exit-status

Rerun Workflows

# Rerun entire workflow
gh run rerun <run-id>

# Rerun only failed jobs
gh run rerun <run-id> --failed

# Rerun with debug logging
gh run rerun <run-id> --debug

Cancel Workflows

# Cancel specific run
gh run cancel <run-id>

Analysis Patterns

Find Recent Failures

# Get last 10 failed runs
gh run list --status=failure --limit 10

# Get failures with details
gh run list --workflow=ci.yml --status=failure --limit 5 \
  --json databaseId,conclusion,name,createdAt,headBranch,headSha

Identify Flaky Tests

# Get runs for specific commit
gh run list --commit=<sha>

# Find tests that sometimes pass
gh run list --workflow=test.yml --limit 20 --json conclusion \
  | jq 'group_by(.conclusion) | map({conclusion: .[0].conclusion, count: length})'

Extract Error Messages

# View failed logs
gh run view <run-id> --log-failed

# Extract error lines
gh run view <run-id> --log-failed | grep -i "error\|failed\|exception"

# Parse JSON for errors
gh api repos/:owner/:repo/actions/runs/<run-id>/jobs \
  | jq '.jobs[] | select(.conclusion == "failure") | {name, steps: [.steps[] | select(.conclusion == "failure")]}'

Check Workflow Timing

# Get run duration
gh run view <run-id> --json startedAt,completedAt,durationMs

# Compare run times
gh run list --workflow=ci.yml --limit 10 \
  --json databaseId,createdAt,updatedAt,durationMs \
  | jq '.[] | {id: .databaseId, duration_min: (.durationMs / 60000)}'

Monitor Workflow Status

# Check current status
gh run list --status=in_progress

# Summary of run statuses
gh run list --limit 50 --json conclusion \
  | jq 'group_by(.conclusion) | map({conclusion: .[0].conclusion, count: length})'

Common Failure Pattern Summary

| Pattern | Symptoms | Quick Fix | |---------|----------|-----------| | Authentication | "403 Forbidden", "Resource not accessible" | Check GITHUB_TOKEN scope, workflow permissions | | Timeout | "exceeded maximum execution time" | Increase timeout-minutes, split parallel jobs | | Flaky tests | Same test passes/fails inconsistently | Fix race conditions, mock external deps | | Dependency install | "Could not find package", "Version conflict" | Lock versions, use cache | | Environment | "Command not found", "Module not found" | Verify setup steps, check runner version | | Resource constraints | "out of disk space", "Process killed" | Clean artifacts, increase runner size |

Agentic Optimizations

| Context | Command | |---------|---------| | Quick failure check | gh run list --status=failure --limit 5 --json databaseId,conclusion,name | | Failed logs only | gh run view <id> --log-failed | | JSON run details | gh run view <id> --json status,conclusion,jobs | | Failure rate | gh run list --limit 50 --json conclusion \| jq 'group_by(.conclusion)' | | Rerun failed only | gh run rerun <id> --failed |

Quick Reference

gh run Commands

• gh run list - List workflow runs
• gh run view <id> - View run details
• gh run watch <id> - Watch run progress
• gh run download <id> - Download logs/artifacts
• gh run rerun <id> - Rerun workflow
• gh run cancel <id> - Cancel running workflow

Useful Filters

• --workflow=<name> - Specific workflow
• --status=<status> - Filter by status (in_progress, completed, queued, waiting)
• --conclusion=<conclusion> - Filter by conclusion (success, failure, cancelled, skipped)
• --branch=<branch> - Specific branch
• --event=<event> - Specific trigger event
• --limit=<n> - Limit results
• --json <fields> - JSON output

Status Values

• queued - Waiting to start
• in_progress - Currently running
• completed - Finished (check conclusion)
• waiting - Waiting for approval

Conclusion Values

• success - All jobs succeeded
• failure - At least one job failed
• cancelled - Manually cancelled
• skipped - Skipped (conditional)
• timed_out - Exceeded time limit

Integration with Other Skills

This skill complements:

• claude-code-github-workflows - Creating workflows
• github-actions-mcp-config - MCP configuration
• github-actions-auth-security - Authentication setup

Resources

• gh CLI Manual: https://cli.github.com/manual/gh_run
• GitHub Actions API: https://docs.github.com/en/rest/actions
• Troubleshooting Guide: https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows