github-actions-inspection

created	"2025-12-16T00:00:00.000Z"
modified	"2026-04-25T00:00:00.000Z"
reviewed	"2026-04-25T00:00:00.000Z"
name	github-actions-inspection
description	Inspect GitHub Actions runs, analyze logs, debug failures. Use when investigating CI/CD failures, checking workflow status, or debugging GitHub Actions issues.
user-invocable	false
allowed-tools	Bash, Read, Grep, Glob, mcp__github

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