GitHub Actions Inspection

When to Use This Skill

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")]}'

Read job conclusions, not the workflow's

A run's conclusion: success also covers jobs that were skipped. Jobs gated on a tag push or a release event (if: github.event_name == 'push', if: startsWith(github.ref, 'refs/tags/'), release-please pre-release only) report skipped on every PR, so PR CI is green for them by construction. A change that breaks one merges cleanly and fails on the next release, which can be weeks later.

gh run view <run-id> --json jobs --jq '.jobs[] | {name, conclusion}'

• To judge whether a specific job (an image build, a release upload) actually ran, read that job's conclusion. skipped means it verified nothing.
• Before merging a change to a release-gated job, exercise it: trigger it with workflow_dispatch, push a throwaway tag, or run the step locally (for example docker build --file <Dockerfile> .).

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

Agentic Optimizations

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